diff options
Diffstat (limited to 'doc/user')
415 files changed, 5968 insertions, 4029 deletions
diff --git a/doc/user/admin_area/settings/img/protected_paths.png b/doc/user/admin_area/settings/img/protected_paths.png Binary files differdeleted file mode 100644 index 2233a71a139..00000000000 --- a/doc/user/admin_area/settings/img/protected_paths.png +++ /dev/null diff --git a/doc/user/admin_area/settings/slack_app.md b/doc/user/admin_area/settings/slack_app.md index 5aae85081ed..86762edd1a9 100644 --- a/doc/user/admin_area/settings/slack_app.md +++ b/doc/user/admin_area/settings/slack_app.md @@ -1,109 +1,11 @@ --- -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 +redirect_to: '../../../administration/settings/slack_app.md' +remove_date: '2023-10-14' --- -# GitLab for Slack app administration **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/slack_app.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. - -NOTE: -This page contains information about administering the GitLab for Slack app for self-managed instances. For user documentation, see [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md). - -The GitLab for Slack app distributed through the Slack App Directory only works with GitLab.com. -On self-managed GitLab, you can create your own copy of the GitLab for Slack app from a [manifest file](https://api.slack.com/reference/manifests#creating_apps) and configure your instance. - -The app is a private one-time copy installed in your Slack workspace only and not distributed through the Slack App Directory. To have the [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md) on your self-managed instance, you must enable the integration. - -## Create a GitLab for Slack app - -Prerequisite: - -- You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). - -To create a GitLab for Slack app: - -- **In GitLab**: - - 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 **GitLab for Slack app**. - 1. Select **Create Slack app**. - -You're then redirected to Slack for the next steps. - -- **In Slack**: - - 1. Select the Slack workspace to create the app in, then select **Next**. - 1. Slack displays a summary of the app for review. To view the complete manifest, select **Edit Configurations**. To go back to the review summary, select **Next**. - 1. Select **Create**. - 1. Select **Got it** to close the dialog. - 1. Select **Install to Workspace**. - -## Configure the settings - -After you've [created a GitLab for Slack app](#create-a-gitlab-for-slack-app), you can configure the settings in GitLab: - -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 **GitLab for Slack app**. -1. Select the **Enable GitLab for Slack app** checkbox. -1. Enter the details of your GitLab for Slack app: - 1. Go to [Slack API](https://api.slack.com/apps). - 1. Search for and select **GitLab (\<your host name\>)**. - 1. Scroll to **App Credentials**. -1. Select **Save changes**. - -### Test your configuration - -To test your GitLab for Slack app configuration: - -1. Enter the `/gitlab help` slash command into a channel in your Slack workspace. -1. Press <kbd>Enter</kbd>. - -You should see a list of available Slash commands. - -To use Slash commands for a project, configure the [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md) for the project. - -## Update the GitLab for Slack app - -When GitLab releases new features for the GitLab for Slack app, you might have to manually update your copy to use the new features. - -To update your copy of the GitLab for Slack app: - -- **In GitLab**: - - 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 **GitLab for Slack app**. - 1. Select **Download latest manifest file** to download `slack_manifest.json`. - -- **In Slack**: - - 1. Go to [Slack API](https://api.slack.com/apps). - 1. Search for and select **GitLab (\<your host name\>)**. - 1. On the left sidebar, select **App Manifest**. - 1. Select the **JSON** tab to switch to a JSON view of the manifest. - 1. Copy the contents of the `slack_manifest.json` file you've downloaded from GitLab. - 1. Paste the contents into the JSON viewer to replace any existing contents. - 1. Select **Save Changes**. - -## Connectivity requirements - -To enable the GitLab for Slack app functionality, your network must allow inbound and outbound connections between GitLab and Slack. - -- For [Slack notifications](../../../user/project/integrations/gitlab_slack_application.md#slack-notifications), the GitLab instance must be able to send requests to `https://slack.com`. -- For [Slash commands](../../../user/project/integrations/gitlab_slack_application.md#slash-commands) and other features, the GitLab instance must be able to receive requests from `https://slack.com`. - -## Troubleshooting - -### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack - -Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure: - -- The GitLab for Slack app is properly [configured](#configure-the-settings), and the **Enable GitLab for Slack app** checkbox is selected. -- Your GitLab instance [allows requests to and from Slack](#connectivity-requirements). +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index b9bcaec8b57..9558e40d56f 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -1,6 +1,6 @@ --- -stage: ModelOps -group: AI Assisted +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 --- @@ -40,15 +40,26 @@ The following feature is Generally Available: [Beta features](../policy/experiment-beta-support.md#beta) do not require [Experiment features to be enabled](group/manage.md#enable-experiment-features). -The following feature is in Beta: +The following features are in Beta: - [Code Suggestions](project/repository/code_suggestions.md) +- [Explain this vulnerability](application_security/vulnerabilities/index.md#explaining-a-vulnerability-beta) ## Experiment AI features [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 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) + +The rest of the features described on this page are also in the Experiment phase. + ### Explain Selected Code in the Web UI **(ULTIMATE SAAS)** > Introduced in GitLab 15.11 as an [Experiment](../policy/experiment-beta-support.md#experiment) on GitLab.com. @@ -98,136 +109,108 @@ code in a merge request: We cannot guarantee that the large language model produces results that are correct. Use the explanation with caution. -### Explain this Vulnerability in the Web UI **(ULTIMATE SAAS)** +### GitLab Duo Chat **(ULTIMATE SAAS)** -> [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. +> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by Google AI. +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -GitLab can help you with your vulnerability by using a large language model to: +GitLab Duo Chat is powered by Anthropic's Claude-2.0 and Claude-instant-1.1 large language models and OpenAI's text-embedding-ada-002 embeddings. The LLMs are employed to analyze user questions to collect appropriate context data from the user's project, and to generate responses. In some cases, embeddings are used to embed user questions and find relevant content in GitLab documentation to share with the LLMs to generate an answer. -- Summarize the vulnerability. -- Help developers and security analysts get started understanding the vulnerability, how it could be exploited, and how to fix it. -- Provide a suggested mitigation. +You can get AI generated support from GitLab Duo Chat about the following topics: -Prerequisites: +- How to use GitLab. +- Questions about an issue. +- Summarizing an issue. -- You must have the GitLab Ultimate subscription tier. -- You must be a member of the project. -- The vulnerability must be a SAST finding. +Example questions you might ask: -To explain your vulnerability: +- `What is a fork?` +- `How to reset my password` +- `Summarize the issue <link to your issue>` +- `Summarize the description of the current issue` -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, select **Secure > Vulnerability report**. -1. Find a SAST vulnerability. -1. Open the vulnerability. -1. Select **Try it out**. - -Review the drawer on the right-hand side of your screen. - - +The examples above all use data from either the issue or the GitLab documentation. However, you can also ask to generate code, CI/CD configurations, or to explain code. For example: -We cannot guarantee that the large language model produces results that are correct. Use the explanation with caution. +- `Write a hello world function in Ruby` +- `Write a tic tac toe game in JavaScript` +- `Write a .gitlab-ci.yml file to test and build a rails application` +- `Explain the following code: def sum(a, b) a + b end` -### GitLab Duo Chat **(ULTIMATE SAAS)** +You can also ask follow-up questions. -> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). - -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. - -Getting help has never been easier. If you have a question about how the GitLab product works, you can ask product how-to questions and get AI generated support from GitLab Duo Chat. +This is an experimental feature and we're continuously extending the capabilities and reliability of the chat. 1. In the lower-left corner, select the Help icon. + The [new left sidebar must be enabled](../tutorials/left_sidebar/index.md#enable-the-new-left-sidebar). 1. Select **Ask in GitLab Duo Chat**. A drawer opens on the right side of your screen. -1. Enter your question in the chat input box and press **Enter** or select **Send**. It may take a few seconds for the interactive AI chat to search the product documentation and produce an answer. +1. Enter your question in the chat input box and press **Enter** or select **Send**. It may take a few seconds for the interactive AI chat to produce an answer. +1. You can ask a follow-up question. +1. If you want to ask a new question unrelated to the previous conversation, you may receive better answers if you clear the context by typing `/reset` into the input box and selecting **Send**. -To give feedback, select the **Give Feedback** link. +To give feedback about a specific response, use the feedback buttons in the response message. +Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/415591). NOTE: -Only the last 50 messages in the chat history are retained. The chat history expires 3 days after last use. - -### Summarize merge request changes **(ULTIMATE SAAS)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10400) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). - -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. - -You can generate a merge request summary in a merge request comment. - -- In a comment, type `/summarize_diff`. - -This action posts a comment from a GitLab bot. The comment provides a summary of the changes and the related SHA for when that summary was generated. - -Provide feedback on this experimental feature in [issue 408726](https://gitlab.com/gitlab-org/gitlab/-/issues/408726). - -**Data usage**: When you use this quick action, the diff of changes between the head of the source branch -and the target branch is sent to the large language model referenced above. - -### Summarize my merge request review **(ULTIMATE SAAS)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10466) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +Only the last 50 messages are retained in the chat history. The chat history expires 3 days after last use. -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. - -When you've completed your review of a merge request and are ready to [submit your review](project/merge_requests/reviews/index.md#submit-a-review), you can have a summary generated for you. - -To generate the summary: - -1. When you are ready to submit your review, select **Finish review**. -1. Select **AI Actions** (**{tanuki}**). -1. Select **Summarize my code review**. +### Summarize issue discussions **(ULTIMATE SAAS)** -The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). -Provide feedback on this experimental feature in [issue 408991](https://gitlab.com/gitlab-org/gitlab/-/issues/408991). +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's +GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: +You can generate a summary of discussions on an issue: -- Draft comment's text -- File path of the commented files +1. In an issue, scroll to the **Activity** section. +1. Select **View summary**. -### Generate suggested tests in merge requests **(ULTIMATE SAAS)** +The comments in the issue are summarized in as many as 10 list items. +The summary is displayed only for you. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10366) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +Provide feedback on this experimental feature in [issue 407779](https://gitlab.com/gitlab-org/gitlab/-/issues/407779). -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. +**Data usage**: When you use this feature, the text of public comments on the issue are sent to the large +language model referenced above. -In a merge request, you can get a list of suggested tests for the file you are reviewing. This functionality can help determine if appropriate test coverage has been provided, or if you need more coverage for your project. +### Show deployment frequency forecast **(ULTIMATE SAAS)** -To generate a test suggestion: +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10228) in GitLab 16.2 as an [Experiment](../policy/experiment-beta-support.md#experiment). -1. In a merge request, select the **Changes** tab. -1. On the header for the file, in the upper-right corner, select **Options** (**{ellipsis_v}**). -1. Select **Suggest test cases**. +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com. -The test suggestion is generated in a sidebar. You can copy the suggestion to your editor and use it as the start of your tests. +In CI/CD Analytics, you can view a forecast of deployment frequency: -Feedback on this experimental feature can be provided in [issue 408995](https://gitlab.com/gitlab-org/gitlab/-/issues/408995). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > CI/CD analytics**. +1. Select the **Deployment frequency** tab. +1. Turn on the **Show forecast** toggle. +1. On the confirmation dialog, select **Accept testing terms**. -**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: +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. -- Contents of the file -- The file name +Provide feedback on this experimental feature in [issue 416833](https://gitlab.com/gitlab-org/gitlab/-/issues/416833). -### Summarize issue discussions **(ULTIMATE SAAS)** +### Generate issue descriptions **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10762) in GitLab 16.3 as an [Experiment](../policy/experiment-beta-support.md#experiment). This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -You can generate a summary of discussions on an issue: +You can generate the description for an issue from a short summary. -1. In an issue, scroll to the **Activity** section. -1. Select **View summary**. +1. Create a new issue. +1. Above the **Description** field, select **AI actions > Generate issue description**. +1. Write a short description and select **Submit**. -The comments in the issue are summarized in as many as 10 list items. -The summary is displayed only for you. +The issue description is replaced with AI-generated text. -Provide feedback on this experimental feature in [issue 407779](https://gitlab.com/gitlab-org/gitlab/-/issues/407779). +Provide feedback on this experimental feature in [issue 409844](https://gitlab.com/gitlab-org/gitlab/-/issues/409844). -**Data usage**: When you use this feature, the text of public comments on the issue are sent to the large +**Data usage**: When you use this feature, the text you enter is sent to the large language model referenced above. ## Data Usage @@ -236,7 +219,7 @@ GitLab AI features leverage generative AI to help increase velocity and aim to h ### Progressive enhancement -These features are designed as a progressive enhancement to existing GitLab features across our DevSecOps platform. They are designed to fail gracefully and should not prevent the core functionality of the underlying feature. Please note each feature is subject to its expected functionality as defined by the relevant [feature support policy](../policy/experiment-beta-support.md). +These features are designed as a progressive enhancement to existing GitLab features across our DevSecOps platform. They are designed to fail gracefully and should not prevent the core functionality of the underlying feature. You should note each feature is subject to its expected functionality as defined by the relevant [feature support policy](../policy/experiment-beta-support.md). ### Stability and performance @@ -246,7 +229,7 @@ These features are in a variety of [feature support levels](../policy/experiment ### Data privacy -Some AI features require the use of third-party AI services models and APIs from: Google AI and OpenAI. The processing of any personal data is in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). You may also visit the [Sub-Processors page](https://about.gitlab.com/privacy/subprocessors/#third-party-sub-processors) to see the list of our Sub-Processors that we use in order to provide these features. +Some AI features require the use of third-party AI services models and APIs from: Google AI and OpenAI. The processing of any personal data is in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). You may also visit the [Sub-Processors page](https://about.gitlab.com/privacy/subprocessors/#third-party-sub-processors) to see the list of our Sub-Processors that we use to provide these features. Group owners can control which top-level groups have access to third-party AI features by using the [group level third-party AI features setting](group/manage.md#enable-third-party-ai-features). @@ -261,4 +244,4 @@ Generative AI may produce unexpected results that may be: - Insecure code - Offensive or insensitive -GitLab is actively iterating on all our AI-assisted capabilities to improve the quality of the generated content. We will continue improving the quality through prompt engineering, evaluating new AI/ML models to power these features, and through novel heuristics built into these features directly. +GitLab is actively iterating on all our AI-assisted capabilities to improve the quality of the generated content. We improve the quality through prompt engineering, evaluating new AI/ML models to power these features, and through novel heuristics built into these features directly. diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index 9d2c91b6bc8..49870e8c66c 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)** +# Analytics dashboards (Experiment) **(ULTIMATE ALL)** > 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. @@ -24,17 +24,24 @@ filters and visualizations to query and retrieve results. The following data sources are configured for analytics dashboards: - [Product analytics](../product_analytics/index.md) +- [Value Stream Management](../analytics/value_streams_dashboard.md) ## Built-in dashboards -To help you get started with analytics, GitLab provides two built-in dashboards with predefined visualizations: +To help you get started with analytics, GitLab provides built-in dashboards with predefined visualizations. -- **Audience**, which displays metrics related to traffic, such as number of users and sessions. -- **Behavior**, which displays metrics related to user activity, such as number of page views and events. +### Product analytics + +- **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). + ## Custom dashboards With custom dashboards, you can design and create visualizations for the metrics that are most relevant to your use case. @@ -69,10 +76,14 @@ You can use the dashboard designer to: ## View project dashboards +Prerequisite: + +- You must have at least the Developer role for the project. + 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. Select **Analyze > Dashboards**. +1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. ## Change the location of dashboards @@ -170,7 +181,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. Select **Analyze > Dashboards**. +1. Select **Analyze > Analytics dashboards**. 1. Select **New dashboard**. 1. In the **New dashboard** input, enter the name of the dashboard. 1. From the **Add visualizations** list on the right, select the visualizations to add to the dashboard. @@ -184,7 +195,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. Select **Analyze > Dashboards**. +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**. 1. Optional. Change the title of the dashboard. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index daee21d2567..8dc69b2f664 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.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 --- -# CI/CD analytics **(FREE)** +# CI/CD analytics **(FREE ALL)** Use the CI/CD analytics page to view pipeline success rates and duration, and the history of DORA metrics over time. @@ -35,7 +35,7 @@ To view CI/CD analytics: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Analyze > CI/CD analytics**. -## View DORA deployment frequency chart **(ULTIMATE)** +## View DORA deployment frequency chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. @@ -56,7 +56,7 @@ To view the deployment frequency chart:  -## View DORA lead time for changes chart **(ULTIMATE)** +## View DORA lead time for changes chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250329) in GitLab 13.11. @@ -78,7 +78,7 @@ To view the lead time for changes chart:  -## View DORA time to restore service chart **(ULTIMATE)** +## View DORA time to restore service chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356959) in GitLab 15.1 @@ -94,7 +94,7 @@ To view the time to restore service chart:  -## View DORA change failure rate chart **(ULTIMATE)** +## View DORA change failure rate chart **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357072) in GitLab 15.2 diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 646a85fc7a2..27d3e45803e 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -5,7 +5,7 @@ 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 --- -# Code review analytics **(PREMIUM)** +# Code review analytics **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/analytics/contributor_statistics.md b/doc/user/analytics/contributor_statistics.md new file mode 100644 index 00000000000..514f1ca42ab --- /dev/null +++ b/doc/user/analytics/contributor_statistics.md @@ -0,0 +1,48 @@ +--- +stage: Plan +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 +--- + +# Contributor statistics **(FREE ALL)** + +Contributor statistics give you an overview of the commits made by projects members to a project over time. + +## View contributor statistics + +The contributor statistics page displays a line chart with the number of commits to the selected project branch over time, +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. 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. +1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: + + - To change the start date, slide the left pause icon to the left or right. + - To change the end date, slide the right pause icon to the left or right. + +## View project commit history + +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. Select **Analyze > Contributor statistics**. +1. Select **History**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made by the members on a specific day, hover over the line chart. +1. Optional. Filter the results. + + - To filter by author, from the **Author** dropdown list, select the user whose commits you want to view. + - To filter by commit message, in the text box, enter your search criteria. + +## Retrieve project commits as an RSS feed + +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. 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 bdfeffcec05..0efe4a53427 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -4,7 +4,7 @@ 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 --- -# DevOps Research and Assessment (DORA) metrics **(ULTIMATE)** +# 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. @@ -131,9 +131,9 @@ To improve this metric, you should consider: The DORA metrics are displayed on the following charts: -- [Value Streams Dashboard](value_streams_dashboard.md), which helps you identify trends, patterns, and opportunities for improvement. +- [Value Streams Dashboard](value_streams_dashboard.md), which helps you identify trends, patterns, and opportunities for improvement. DORA metrics are displayed in the [metrics comparison panel](value_streams_dashboard.md#devsecops-metrics-comparison-panel) and the [DORA Performers score panel](value_streams_dashboard.md#dora-performers-score-panel). - [CI/CD analytics charts](ci_cd_analytics.md), which show pipeline success rates and duration, and the history of DORA metrics over time. -- Insights reports for [groups](../group/insights/index.md) and [projects](value_stream_analytics.md), where you can also use [DORA query parameters](../../user/project/insights/index.md#dora-query-parameters) to create custom charts. +- Insights reports for [groups](../group/insights/index.md) and [projects](../group/value_stream_analytics/index.md), where you can also use [DORA query parameters](../../user/project/insights/index.md#dora-query-parameters) to create custom charts. The table below provides an overview of the DORA metrics' data aggregation in different charts. 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 differnew file mode 100644 index 00000000000..9f59667f9e9 --- /dev/null +++ b/doc/user/analytics/img/dora_performers_score_panel_v16_3.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index c057a8b193d..abeda983dad 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -4,7 +4,7 @@ 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 --- -# Analyze GitLab usage **(FREE)** +# Analyze GitLab usage **(FREE ALL)** ## Instance-level analytics @@ -27,7 +27,7 @@ GitLab provides several analytics features at the group level. Some of these fea - [Issue](../group/issues_analytics/index.md) - [Productivity](productivity_analytics.md) - [Repositories](../group/repositories_analytics/index.md) -- [Value Stream Management Analytics](value_stream_analytics.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) +- [Value Stream Management Analytics](../group/value_stream_analytics/index.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) ## Project-level analytics @@ -38,12 +38,13 @@ You can use GitLab to review analytics at the project level. Some of these featu - [Application Security](../application_security/security_dashboard/index.md) - [CI/CD & DORA](ci_cd_analytics.md) - [Code Review](code_review_analytics.md) +- [Contributor statistics](../../user/analytics/contributor_statistics.md) - [Insights](../project/insights/index.md) -- [Issue](../group/issues_analytics/index.md) +- [Issue](../../user/analytics/issue_analytics.md) - [Merge Request](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](value_stream_analytics.md), and [Value Stream Management Dashboard](value_streams_dashboard.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 @@ -67,8 +68,7 @@ Be sure to review the documentation page for this feature for GitLab tier requir You can use the following analytics features to analyze and visualize the performance of your projects and groups: -- [Value stream analytics for projects](value_stream_analytics.md) -- [Value stream analytics for groups](../group/value_stream_analytics/index.md) +- [Value stream analytics for projects and groups](../group/value_stream_analytics/index.md) - [Value streams dashboard](value_streams_dashboard.md) ## Glossary diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index aaf33f48df2..7caee947318 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -5,7 +5,7 @@ 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 --- -# Issue analytics for projects **(PREMIUM)** +# Issue analytics for projects **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index eeaa8271749..998f56ac40a 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -5,7 +5,7 @@ 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 --- -# Merge request analytics **(PREMIUM)** +# Merge request analytics **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in GitLab 13.3. > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index f53b516dd0d..ea896f07204 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -4,7 +4,7 @@ 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 --- -# Productivity analytics **(PREMIUM)** +# Productivity analytics **(PREMIUM ALL)** You can use productivity analytics to identify: diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index e686d76eda2..46fa36658c4 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -4,7 +4,7 @@ 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 --- -# Repository analytics for projects **(FREE)** +# Repository analytics for projects **(FREE ALL)** Use repository analytics to view information about a project's Git repository: diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md deleted file mode 100644 index 292a6f430d9..00000000000 --- a/doc/user/analytics/value_stream_analytics.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -remove_date: '2023-07-22' -redirect_to: '../group/value_stream_analytics/index.md' ---- - -# Value stream analytics for projects **(FREE)** - -This document was moved to [another location](../group/value_stream_analytics/index.md). - -<!-- This redirect file can be deleted after 2023-07-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/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index a853263d20f..2c6626ad315 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -4,19 +4,17 @@ 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 --- -# Value Streams Dashboard **(ULTIMATE)** +# Value Streams Dashboard **(ULTIMATE ALL)** > - Introduced in GitLab 15.8 as a Closed [Beta](../../policy/experiment-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Disabled by default. > - 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 381787](https://gitlab.com/gitlab-org/gitlab/-/issues/381787). +You can leave feedback on dashboard bugs or functionality in [issue 419488](https://gitlab.com/gitlab-org/gitlab/-/issues/419488). 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. - -With the Value Streams Dashboard, you can compare software delivery metrics. -This comparison can help you understand whether projects and groups are improving. +The centralized UI in Value Streams Dashboard acts as the single source of truth (SSOT), where all stakeholders can access and view the same set of metrics that are relevant to the organization. The Value Streams Dashboard includes the following metrics: @@ -24,14 +22,16 @@ The Value Streams Dashboard includes the following metrics: - [Value Stream Analytics (VSA) - flow metrics](../group/value_stream_analytics/index.md) - [Vulnerabilities](https://gitlab.com/gitlab-org/gitlab/-/security/vulnerability_report) metrics. -The Value Streams Dashboard allows you to: +With the Value Streams Dashboard, you can: -- Aggregate data records from different APIs. -- Track software performance (DORA) and flow of value (VSA) across the organization. +- Track and compare the above metrics over a period of time. +- Identify downward trends early on. +- Understand security exposure. +- Drill down into individual projects or metrics to take actions for improvement. -## DevOps metrics comparison panel +## DevSecOps metrics comparison panel -The DevOps metrics comparison displays DORA4 and flow metrics for a group or project in the +The DevSecOps metrics comparison displays DORA4, vulnerability, and flow metrics for a group or project in the month-to-date, last month, the month before, and the past 180 days. This visualization helps you get a high-level custom view over multiple DevOps metrics and @@ -44,19 +44,52 @@ that are the largest value contributors, overperforming, or underperforming. You can also drill down the metrics for further analysis. When you hover over a metric, a tooltip displays an explanation of the metric and a link to the related documentation page. +## DORA Performers score panel + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386843) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. Disabled by default. + +FLAG: +By default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `dora_performers_score_panel`. + +The [DORA metrics](dora_metrics.md) Performers score panel is a bar chart that visualizes the status of the organization's DevOps performance levels across different projects. + +The chart is a breakdown of your project's DORA scores, categorized as high, medium, or low. +It aggregates all the child projects in the group. + +Each bar on the chart displays the sum of total projects per score category, calculated monthly. +To exclude data from the chart (for example, "Not Included"), in the legend select the series you want to exclude. +Hovering over each bar reveals a dialog that explains the score's definition. + +For example, if a project has a high score for Deployment Frequency (Velocity), it means that the project has one or more deploys to production per day. + +| Metric | Description | High | Medium | Low | +|--------|-------------|------|--------|-----| +| Deployment frequency | The number of deploys to production per day | ≥30 | 1-29 | \<1 | +| Lead time for changes | The number of days to go from code committed to code successfully running in production| ≤7 | 8-29 | ≥30 | +| Time to restore service | The number of days to restore service when a service incident or a defect that impacts users occurs | ≤1 | 2-6 | ≥7 | +| Change failure rate | The percentage of changes to production resulted in degraded service | ≤15% | 16%-44% | ≥45% | + +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). + ## View the value streams dashboard Prerequisite: -- To view the value streams dashboard for a group, you must have at least the Reporter role for the group. +- You must have at least the Reporter role for the group. To view the value streams dashboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to 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`). +- From Analytics Dashboards: + + 1. On the group left sidebar, at the top, select **Search GitLab** (**{search}**) to 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. 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`). ## Customize the dashboard panels @@ -117,7 +150,6 @@ description: 'Custom description' # * issues # * issues_completed # * merge_request_throughput -# (This option is dependant on the `vsd_graphql_dora_and_flow_metrics` feature.) panels: - title: 'My Custom Project' data: @@ -164,3 +196,13 @@ For an overview of editing label filters in the configuration file, see [GitLab | Merge request throughput | The number of merge requests merged by month. | [Groups Productivity analytics](productivity_analytics.md), [Projects Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Groups Productivity analytics](productivity_analytics.md) [Projects Merge request analytics](merge_request_analytics.md) | `merge_request_throughput` | | Critical vulnerabilities over time | Critical vulnerabilities over time in project or group | [Vulnerability report](https://gitlab.com/gitlab-org/gitlab/-/security/vulnerability_report) | [Vulnerability report](../application_security/vulnerability_report/index.md) | `vulnerability_critical` | | High vulnerabilities over time | High vulnerabilities over time in project or group | [Vulnerability report](https://gitlab.com/gitlab-org/gitlab/-/security/vulnerability_report) | [Vulnerability report](../application_security/vulnerability_report/index.md) | `vulnerability_high` | + +## Value Streams Dashboard metrics with Jira + +The following metrics do not depend on using Jira: + +- DORA Deployment frequency +- DORA Lead time for changes +- Number of deploys +- Merge request throughput +- Vulnerabilities diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 0ad87facc50..b82ea30b463 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# HTTP Archive format **(ULTIMATE)** +# HTTP Archive format **(ULTIMATE ALL)** HTTP Archive (HAR) format files are an industry standard for exchanging information about HTTP requests and HTTP responses. A HAR file's content is JSON formatted, containing browser interactions diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e8feb0f4a59..c365c7f6bab 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Web API Fuzz Testing **(ULTIMATE)** +# Web API Fuzz Testing **(ULTIMATE ALL)** Web API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API @@ -1108,7 +1108,7 @@ profile increases as the number of tests increases. |[`FUZZAPI_EXCLUDE_PARAMETER_ENV`](#exclude-parameters) | JSON string containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | |[`FUZZAPI_EXCLUDE_PARAMETER_FILE`](#exclude-parameters) | Path to a JSON file containing excluded parameters. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | -|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. Introduced in GitLab 14.7. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/345950`. | |[`FUZZAPI_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | diff --git a/doc/user/application_security/api_security/api_discovery/index.md b/doc/user/application_security/api_security/api_discovery/index.md index c7ae47a7083..0d7bb2830e9 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# API Discovery **(ULTIMATE)** +# API Discovery **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9302) in GitLab 15.9. The API Discovery feature is in [Beta](../../../../policy/experiment-beta-support.md). diff --git a/doc/user/application_security/api_security/index.md b/doc/user/application_security/api_security/index.md index 5c2e74bceae..37549d5db51 100644 --- a/doc/user/application_security/api_security/index.md +++ b/doc/user/application_security/api_security/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# API Security **(ULTIMATE)** +# API Security **(ULTIMATE ALL)** API Security refers to the measures taken to secure and protect web Application Programming Interfaces (APIs) from unauthorized access, misuse, and attacks. APIs are a crucial component of modern application development as they allow applications to interact with each other and exchange data. diff --git a/doc/user/application_security/breach_and_attack_simulation/index.md b/doc/user/application_security/breach_and_attack_simulation/index.md index bb67150d4fa..dab625bc169 100644 --- a/doc/user/application_security/breach_and_attack_simulation/index.md +++ b/doc/user/application_security/breach_and_attack_simulation/index.md @@ -5,7 +5,7 @@ info: Breach and Attack Simulation is a GitLab Incubation Engineering program. N type: reference, howto --- -# Breach and Attack Simulation **(ULTIMATE)** +# Breach and Attack Simulation **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/402784) in GitLab 15.11 as an Incubating feature. > - [Included](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119981) in the `Security/BAS.latest.gitlab-ci.yml` in GitLab 16.0. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index bbb7bf2f625..10e16a173d8 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -5,7 +5,7 @@ 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 --- -# Security configuration **(FREE)** +# 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. @@ -73,12 +73,9 @@ You can configure the following security controls: - [Coverage Fuzzing](../coverage_fuzzing/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#enable-coverage-guided-fuzz-testing). -## Compliance **(ULTIMATE)** +## Compliance **(ULTIMATE ALL)** You can configure the following security controls: -- [License Compliance](../../../user/compliance/license_compliance/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#enable-license-compliance). - - [Security Training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities) - Enable **Security training** for the current project. For more details, read [security training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 791a73bfdc2..04b0bace265 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -5,7 +5,7 @@ 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 --- -# Container Scanning **(FREE)** +# Container Scanning **(FREE ALL)** > - Improved support for FIPS [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) in GitLab 13.6 by upgrading `CS_MAJOR_VERSION` from `2` to `3`. > - Integration with Trivy [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) in GitLab 13.9 by upgrading `CS_MAJOR_VERSION` from `3` to `4`. @@ -430,7 +430,7 @@ container_scanning: The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. -### Vulnerability allowlisting **(ULTIMATE)** +### Vulnerability allowlisting **(ULTIMATE ALL)** To allowlist specific vulnerabilities, follow these steps: @@ -602,7 +602,7 @@ variables: SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:6 TARGET_IMAGE: $CI_REGISTRY/namespace/container-scanning -image: docker:stable +image: docker:latest update-scanner-image: services: @@ -748,7 +748,7 @@ Database update information for other analyzers is available in the After a vulnerability is found, you can [address it](../vulnerabilities/index.md). -## Solutions for vulnerabilities (auto-remediation) **(ULTIMATE)** +## Solutions for vulnerabilities (auto-remediation) **(ULTIMATE ALL)** Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index b0571c8a6ca..59bd2b1ffb3 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/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 --- -# Coverage-guided fuzz testing **(ULTIMATE)** +# Coverage-guided fuzz testing **(ULTIMATE ALL)** Coverage-guided fuzz testing sends random inputs to an instrumented version of your application in an effort to cause unexpected behavior. Such behavior indicates a bug that you should address. diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index 1a68abd01f6..b13b41e4a37 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST authentication **(ULTIMATE)** +# DAST authentication **(ULTIMATE ALL)** WARNING: **DO NOT** use credentials that are valid for production systems, production servers, or any that diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 0338555598c..26782c319b1 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST browser-based analyzer **(ULTIMATE)** +# DAST browser-based analyzer **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12 as a Beta feature. > - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9023) in GitLab 15.7 (GitLab DAST v3.0.50). diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index f659001e7c5..446cd0aaa92 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Troubleshooting DAST browser-based analyzer **(ULTIMATE)** +# Troubleshooting DAST browser-based analyzer **(ULTIMATE ALL)** The following troubleshooting scenarios have been collected from customer support cases. If you experience a problem not addressed here, or the information here does not fix your problem, create a diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index bafe426ca43..1b3ce45dc43 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)** +# DAST browser-based crawler vulnerability checks **(ULTIMATE ALL)** 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. diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index c2e7f153e02..08f819e020c 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Troubleshooting DAST proxy-based analyzer **(ULTIMATE)** +# Troubleshooting DAST proxy-based analyzer **(ULTIMATE ALL)** The following troubleshooting scenarios have been collected from customer support cases. If you experience a problem not addressed here, or the information here does not fix your problem, create a diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 1f4506a22e5..24aadd14dd1 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Dynamic Application Security Testing (DAST) **(ULTIMATE)** +# Dynamic Application Security Testing (DAST) **(ULTIMATE ALL)** If you deploy your web application into a new environment, your application may become exposed to new types of attacks. For example, misconfigurations of your diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 0eec04bfeff..3052fd3a72d 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST proxy-based analyzer **(ULTIMATE)** +# DAST proxy-based analyzer **(ULTIMATE ALL)** The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, @@ -461,7 +461,11 @@ The DAST job does not require the project's repository to be present when runnin ## On-demand scans -> Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. +> - Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. +> - Scheduled on-demand DAST scans [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3 [with a flag](../../../administration/feature_flags.md) named `dast_on_demand_scans_scheduler`. Disabled by default. +> - Scheduled on-demand DAST scans [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. Feature flag `dast_on_demand_scans_scheduler` removed. +> - Runner tags selection [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. 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, @@ -501,7 +505,7 @@ To run an existing on-demand scan: 1. In the scan's row, select **Run scan**. If the branch saved in the scan no longer exists, you must: - + 1. [Edit the scan](#edit-an-on-demand-scan). 1. Select a new branch. 1. Save the edited scan. @@ -510,28 +514,26 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. #### Create an on-demand scan -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. -> - [Feature flag `dast_on_demand_scans_scheduler` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. - -After you create an on-demand scan, you can: +Create an on-demand scan to: - Run it immediately. - Save it to be run in the future. - Schedule it to be run at a specified schedule. +To create an on-demand DAST scan: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Secure > On-demand scans**. 1. Select **New scan**. 1. Complete the **Scan name** and **Description** fields. 1. In the **Branch** dropdown list, select the desired branch. +1. Optional. Select the runner tags. 1. Select **Select scanner profile** or **Change scanner profile** to open the drawer, and either: - Select a scanner profile from the drawer, **or** - Select **New profile**, create a [scanner profile](#scanner-profile), then select **Save profile**. 1. Select **Select site profile** or **Change site profile** to open the drawer, and either: - Select a site profile from the **Site profile library** drawer, or - - Select **New profile** create a [site profile](#site-profile), then select **Save profile**. + - Select **New profile**, create a [site profile](#site-profile), then select **Save profile**. 1. To run the on-demand scan: - Immediately, select **Save and run scan**. @@ -675,6 +677,11 @@ To delete a site profile: Validating a site is required to run an active scan. +Prerequisites: + +- A runner must be available in the project to run a validation job. +- The GitLab server's certificate must be trusted and must not use a self-signed certificate. + To validate a site profile: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. @@ -857,3 +864,9 @@ For details of the report's schema, see the [schema for DAST reports](https://gi WARNING: The JSON report artifacts are not a public API of DAST and their format is expected to change in the future. + +## Troubleshooting + +### `unable to get local issuer certificate` when trying to validate a site profile + +The use of self-signed certificates is not supported and may cause the job to fail with an error message: `unable to get local issuer certificate`. For more information, see [issue 416670](https://gitlab.com/gitlab-org/gitlab/-/issues/416670). diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index a75e5832b7c..0101749be71 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Run DAST in an offline environment **(ULTIMATE)** +# Run DAST in an offline environment **(ULTIMATE ALL)** For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, some adjustments are required for the DAST job to diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index b03f9102dae..ffa2e063535 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST API analyzer **(ULTIMATE)** +# DAST API analyzer **(ULTIMATE ALL)** > DAST API analyzer [became the default analyzer for on-demand DAST API scans](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6. @@ -1059,7 +1059,7 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_REQUEST_HEADERS`](#request-headers) | A comma-separated (`,`) list of headers to include on each scan request. Consider using `DAST_API_REQUEST_HEADERS_BASE64` when storing secret header values in a [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable), which has character set restrictions. | |[`DAST_API_REQUEST_HEADERS_BASE64`](#request-headers) | A comma-separated (`,`) list of headers to include on each scan request, Base64-encoded. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378440) in GitLab 15.6. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | -|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | +|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. Introduced in GitLab 14.7. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/345950` | |[`DAST_API_OPENAPI_ALL_MEDIA_TYPES`](#openapi-specification) | Use all supported media types instead of one when generating requests. Causes test duration to be longer. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_OPENAPI_MEDIA_TYPES`](#openapi-specification) | Colon (`:`) separated media types accepted for testing. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333304) in GitLab 14.10. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | 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 differnew file mode 100644 index 00000000000..f3a8f3d8d5d --- /dev/null +++ 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 d41c0eff860..a55f26f529d 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -5,21 +5,18 @@ 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 --- -# Dependency list **(ULTIMATE)** +# Dependency list **(ULTIMATE ALL)** > - 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. -FLAG: -On self-managed GitLab, by default the group-level dependency list is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies`. On GitLab.com, this feature is not available. - 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. <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 and select **Secure > Dependency list**. +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. @@ -66,6 +63,9 @@ The dependency list shows the path between a dependency and a top-level dependen to, if any. There are many possible paths connecting a transient dependency to top-level dependencies, but the user interface shows only one of the shortest paths. +NOTE: +The dependency path is only displayed for dependencies that have vulnerabilities. +  Dependency paths are supported for the following package managers: @@ -74,21 +74,40 @@ Dependency paths are supported for the following package managers: - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) - [sbt](https://www.scala-sbt.org) -## Licenses +### Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab 12.3. -If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -[discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. +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 your project's full list of dependencies and their details in +You can download the full list of dependencies and their details in `JSON` format. ### In the UI -You can download your 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 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. ### Using the API diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 15fed4f2adc..5a2394113cb 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -4,39 +4,26 @@ 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 --- -# Dependency Scanning **(ULTIMATE)** +# Dependency Scanning **(ULTIMATE ALL)** -The Dependency Scanning feature can automatically find security vulnerabilities in your -software dependencies while you're developing and testing your applications. For example, -dependency scanning lets you know if your application uses an external (open source) -library that is known to be vulnerable. You can then take action to protect your application. +Dependency Scanning analyzes your application's dependencies for known vulnerabilities. All +dependencies are scanned, including transitive dependencies, also known as nested dependencies. Dependency Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain aspects of inspecting the items your code uses. These items typically include application and system dependencies that are almost always imported from external sources, rather than sourced from items you wrote yourself. +Dependency Scanning can run in the development phase of your application's life cycle. Every time a +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. + 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, we encourage you to use all of our security scanners. For a comparison of these features, see [Dependency Scanning compared to Container Scanning](../comparison_dependency_and_container_scanning.md). -If you're using [GitLab CI/CD](../../../ci/index.md), you can use dependency scanning to analyze -your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive -dependencies (also known as nested dependencies). You can take advantage of dependency scanning by -either: - -- [Including the dependency scanning template](#configuration) - in your existing `.gitlab-ci.yml` file. -- Implicitly using - the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) - provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the dependency scanning report, compares the found vulnerabilities -between the source and target branches, and shows the information on the -merge request. The results are sorted by the [severity](../vulnerabilities/severities.md) of the -vulnerability. -  <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -54,12 +41,7 @@ If you're using the shared runners on GitLab.com, this is enabled by default. Th provided are for the Linux/amd64 architecture. WARNING: -If you use your own runners, make sure your installed version of Docker -is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. - -WARNING: -Dependency Scanning does not support run-time installation of compilers and interpreters. -If you need it, explain why by filling out [the survey](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). +Dependency Scanning does not support runtime installation of compilers and interpreters. ## Supported languages and package managers @@ -141,9 +123,10 @@ table.supported-languages ul { <td rowspan="2"> 8 LTS, 11 LTS, - or 17 LTS + 17 LTS, + or 21 EA<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup> </td> - <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup></td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></td> <td> <ul> <li><code>build.gradle</code></li> @@ -175,7 +158,7 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <td><a href="https://pnpm.io/">pnpm</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></td> + <td><a href="https://pnpm.io/">pnpm</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> <td><code>pnpm-lock.yaml</code></td> <td>Y</td> </tr> @@ -188,7 +171,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="4">Python</td> - <td rowspan="4">3.9, 3.10<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> + <td rowspan="4">3.9, 3.10<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> <td><code>setup.py</code></td> <td>N</td> @@ -215,7 +198,7 @@ table.supported-languages ul { <td>N</td> </tr> <tr> - <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> + <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> <td><code>poetry.lock</code></td> <td>N</td> </tr> @@ -234,7 +217,7 @@ table.supported-languages ul { <tr> <td>Scala</td> <td>All versions</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-7">7</a></b></sup></td> <td><code>build.sbt</code></td> <td>N</td> </tr> @@ -251,18 +234,25 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-2"></a> <p> - Gradle is not supported when <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. + Java 21 EA is only available when using <a href="https://maven.apache.org/">Maven</a> and is not supported when + <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. </p> </li> <li> <a id="notes-regarding-supported-languages-and-package-managers-3"></a> <p> - Support for <code>pnpm</code> lockfiles was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336809">introduced in GitLab 15.11</a>. <code>pnpm</code> lockfiles do not store bundled dependencies, so the reported dependencies may differ from <code>npm</code> or <code>yarn</code>. + Gradle is not supported when <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. </p> </li> <li> <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> + Support for <code>pnpm</code> lockfiles was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336809">introduced in GitLab 15.11</a>. <code>pnpm</code> lockfiles do not store bundled dependencies, so the reported dependencies may differ from <code>npm</code> or <code>yarn</code>. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-5"></a> + <p> For support of <code>Python 3.10</code>, add the following stanza to the GitLab CI/CD configuration file. This specifies that the <code>Python 3.10</code> image is to be used, instead of the default <code>Python 3.9</code>. <div class="language-yaml highlighter-rouge"> <div class="highlight"> @@ -272,7 +262,7 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-5"></a> + <a id="notes-regarding-supported-languages-and-package-managers-6"></a> <p> Support for <a href="https://python-poetry.org/">Poetry</a> projects with a <code>poetry.lock</code> file was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/7006">added in GitLab 15.0</a>. Support for projects without a <code>poetry.lock</code> file is tracked in issue: @@ -280,7 +270,7 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-6"></a> + <a id="notes-regarding-supported-languages-and-package-managers-7"></a> <p> Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. </p> @@ -314,9 +304,13 @@ are analyzed. There is no limit to the depth of nested or transitive dependencie Dependency Scanning supports the following official analyzers: +- `gemnasium` +- `gemnasium-maven` +- `gemnasium-python` + +Each of these supported Gemnasium-based Dependency Scanning analyzers exist in the following project: + - [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) -- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) -- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. You can also integrate a custom @@ -339,10 +333,10 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | | Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | | 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 | [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-2">2</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) | +| 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) | -| yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</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) | +| 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) | <!-- markdownlint-disable MD044 --> @@ -357,12 +351,18 @@ The following package managers use lockfiles that GitLab analyzers are capable o <li> <a id="notes-regarding-parsing-lockfiles-2"></a> <p> - Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + Support for NuGet version 2 lock files was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/398680">introduced</a> in GitLab 16.2. </p> </li> <li> <a id="notes-regarding-parsing-lockfiles-3"></a> <p> + Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + </p> + </li> + <li> + <a id="notes-regarding-parsing-lockfiles-4"></a> + <p> Support for Yarn <code>v2</code> and <code>v3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/263358">introduced in GitLab 15.11</a>. However, this feature is also available to versions of GitLab 15.0 and later. </p> <p> @@ -585,10 +585,6 @@ configuration, the last mention of the variable takes precedence. ### Overriding dependency scanning jobs -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. - To override a job definition (for example, to change properties like `variables` or `dependencies`), declare a new job with the same name as the one to override. Place this new job after the template inclusion and specify any additional keys under it. For example, this disables `DS_REMEDIATE` for @@ -632,7 +628,7 @@ The following variables allow configuration of global dependency scanning settin | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](#dependency-analyzers). | | `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | -| `DS_IMAGE_SUFFIX` | Suffix added to the image name. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10.) Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | +| `DS_IMAGE_SUFFIX` | Suffix added to the image name. (Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796`). Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | | `DS_MAX_DEPTH` | Defines how many directory levels deep that the analyzer should search for supported files to scan. A value of `-1` scans all directories regardless of depth. Default: `2`. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). | @@ -649,7 +645,7 @@ The following variables are used for configuring specific analyzers (used for a | `DS_REMEDIATE` | `gemnasium` | `"true"`, `"false"` in FIPS mode | Enable automatic remediation of vulnerable dependencies. Not supported in FIPS mode. | | `DS_REMEDIATE_TIMEOUT` | `gemnasium` | `5m` | Timeout for auto-remediation. | | `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`, `21` | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -678,6 +674,9 @@ variables: HTTPS_PROXY: "https://squid-proxy:3128" ``` +NOTE: +Gradle projects require [an additional variable](#using-a-proxy-with-gradle-projects) setup to use a proxy. + Alternatively we may use it in specific jobs, like Dependency Scanning: ```yaml @@ -716,7 +715,7 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m #### FIPS-enabled images -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10. +> Introduced in GitLab 14.10. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796` GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) versions of the Gemnasium images. You can therefore replace standard images with FIPS-enabled images. @@ -1119,6 +1118,17 @@ gemnasium-dependency_scanning: - tar -xzf gemnasium_db.tar.gz -C $GEMNASIUM_DB_LOCAL_PATH ``` +## Using a proxy with Gradle projects + +The Gradle wrapper script does not read the `HTTP(S)_PROXY` environment variables. See [this upstream issue](https://github.com/gradle/gradle/issues/11065). + +To make the Gradle wrapper script use a proxy, you can specify the options using the `GRADLE_CLI_OPTS` CI/CD variable: + +```yaml +variables: + GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost" +``` + ## 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/generate_test_vulnerabilities/index.md b/doc/user/application_security/generate_test_vulnerabilities/index.md index 76d2227b86b..f9f93b97baf 100644 --- a/doc/user/application_security/generate_test_vulnerabilities/index.md +++ b/doc/user/application_security/generate_test_vulnerabilities/index.md @@ -1,32 +1,6 @@ --- -type: reference, howto -stage: Govern -group: Threat Insights -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: '../../../development/sec/generate_test_vulnerabilities.md' +remove_date: '2023-11-01' --- -# Generate test vulnerabilities - -You can generate test vulnerabilities for the [Vulnerability Report](../vulnerability_report/index.md) to test GitLab -vulnerability management features without running a pipeline. - -1. Login in to GitLab. -1. Go to `/-/profile/personal_access_tokens` and generate a personal access token with `api` permissions. -1. Go to your project page and find the project ID. You can find the project ID below the project title. -1. [Clone the GitLab repository](../../../gitlab-basics/start-using-git.md#clone-a-repository) to your local machine. -1. Open a terminal and go to `gitlab/qa` directory. -1. Run `bundle install` -1. Run the following command: - -```shell -GITLAB_QA_ACCESS_TOKEN=<your_personal_access_token> GITLAB_URL="<address:port>" bundle exec rake vulnerabilities:setup\[<your_project_id>,<vulnerability_count>\] --trace -``` - -Make sure you do the following: - -- Replace `<your_personal_access_token>` with the token you generated in step one. -- Double check the `GITLAB_URL`. It should point to address and port of your GitLab instance, for example `http://localhost:3000` if you are running GDK -- Replace `<your_project_id>` with the ID you obtained in step three above. -- Replace `<vulnerability_count>` with the number of vulnerabilities you'd like to generate. - -The script creates the specified number of placeholder vulnerabilities in the project. +This document was moved to [another location](../../../development/sec/generate_test_vulnerabilities.md). diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index c1524c4b517..ad49f00a1bd 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -4,7 +4,7 @@ group: Technical writing 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 --- -# Get started with GitLab application security **(ULTIMATE)** +# Get started with GitLab application security **(ULTIMATE ALL)** <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Adopting GitLab application security](https://www.youtube.com/watch?v=5QlxkiKR04k). diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 7213fa2ba18..334e8c28378 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -4,7 +4,7 @@ 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 --- -# Infrastructure as Code (IaC) Scanning **(FREE)** +# Infrastructure as Code (IaC) Scanning **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.5. @@ -28,7 +28,7 @@ GitLab IaC Scanning analyzers don't support running on Windows or on any CPU arc WARNING: If you use your own runners, make sure the Docker version installed -is **not** `19.03.0`. See [troubleshooting information](../sast/index.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +is **not** `19.03.0`. See [troubleshooting information](../sast/troubleshooting.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks @@ -128,7 +128,7 @@ To enable IaC Scanning in a project, you can create a merge request: Pipelines now include an IaC Scanning job. -## Customize rulesets **(ULTIMATE)** +## Customize rulesets **(ULTIMATE ALL)** > [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 56a79191833..615ff7e3fda 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -4,7 +4,7 @@ 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 --- -# Application security **(ULTIMATE)** +# Application security **(ULTIMATE ALL)** GitLab can check your application for security vulnerabilities including: @@ -66,7 +66,7 @@ A source code analysis can: Analysis of the web application occurs on every code commit. As part of the CI/CD pipeline, your application is built, deployed to a test environment, and subjected to the following tests: -- Test for known application vectors - [Dynamic Application Security Testing (DAST)](dast/index.md). +- Test application for known attack vectors - [Dynamic Application Security Testing (DAST)](dast/index.md). - Analysis of APIs for known attack vectors - [API Security](dast_api/index.md). - Analysis of web APIs for unknown bugs and vulnerabilities - [API fuzzing](api_fuzzing/index.md). @@ -124,7 +124,6 @@ To enable all GitLab Security scanning tools, with default settings, enable - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) - [Auto DAST](../../topics/autodevops/stages.md#auto-dast) - [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning) -- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance) - [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning) While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customize-gitlab-ciyml). @@ -224,7 +223,7 @@ 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)** +## View security scan information in merge requests **(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. @@ -417,7 +416,6 @@ For more information about overriding security jobs, see: - [Overriding Container Scanning jobs](container_scanning/index.md#overriding-the-container-scanning-template). - [Overriding Secret Detection jobs](secret_detection/index.md#configure-scan-settings). - [Overriding DAST jobs](dast/proxy-based.md#customize-dast-settings). -- [Overriding License Compliance jobs](../compliance/license_compliance/index.md#overriding-the-template). All the security scanning tools define their stage, so this error can occur with all of them. @@ -576,7 +574,7 @@ If a Secure job is failing and it's unclear why: 1. Enable [debug-level logging](#debug-level-logging). 1. Run the job. 1. Examine the job's output. -1. Set the logging level to `info` (default). +1. Remove the `debug` log level to return to the default `info` value. ### Outdated security reports diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 63f3763cab9..1ab26229b50 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -5,7 +5,7 @@ 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 --- -# Offline environments **(ULTIMATE SELF)** +# Offline environments **(FREE SELF)** NOTE: To set up an offline environment, you must receive an [opt-out exemption of cloud licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/#offline-cloud-licensing) prior to purchase. For more details, contact your GitLab sales representative. @@ -93,7 +93,7 @@ above. You can find more information at each of the pages below: - [Secret Detection offline directions](../secret_detection/index.md#running-secret-detection-in-an-offline-environment) - [DAST offline directions](../dast/run_dast_offline.md#run-dast-in-an-offline-environment) - [API Fuzzing offline directions](../api_fuzzing/index.md#running-api-fuzzing-in-an-offline-environment) -- [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) +- [License Scanning offline directions](../../compliance/license_scanning_of_cyclonedx_files/index.md#running-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) ## Loading Docker images onto your offline host diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 4e610d64ec9..59e047ce5c6 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Policies **(ULTIMATE)** +# Policies **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in GitLab 13.10 with a flag named `security_orchestration_policies_configuration`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.3. @@ -150,5 +150,6 @@ The workaround is to amend your group or instance push rules to allow branches f - When enforcing scan execution policies, the target project's pipeline is triggered by the user who last updated the security policy project's `policy.yml` file. The user must have permission to trigger the pipeline in the project for the policy to be enforced, and the pipeline to run. Work to address this is being tracked in [issue 394958](https://gitlab.com/gitlab-org/gitlab/-/issues/394958). - 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. +- When configuring pipeline and scan result policies, it's important to remember that security scans performed in manual jobs aren't verified to determine whether MR approval is required. When you run a manual job with security scans, it won't ensure approval even if vulnerabilities are introduced. If you are still experiencing issues, you can [view recent reported bugs](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=popularity&state=opened&label_name%5B%5D=group%3A%3Asecurity%20policies&label_name%5B%5D=type%3A%3Abug&first_page_size=20) and raise new unreported issues. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index b84d4d2e49e..945d35c89da 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Scan execution policies **(ULTIMATE)** +# Scan execution policies **(ULTIMATE ALL)** > - Group-level security policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. > - Group-level security policies [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. @@ -113,6 +113,11 @@ This rule enforces the defined actions whenever the pipeline runs for a selected > - 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. + +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 GitLab.com, this feature is available. This rule enforces the defined actions and schedules a scan on the provided date/time. @@ -127,6 +132,10 @@ This rule enforces the defined actions and schedules a scan on the provided date 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. + +If the project does not have a security policy bot user, the scheduled scan pipeline is triggered by the user that modified the security policy project last. + GitLab supports the following types of CRON syntax for the `cadence` field: - A daily cadence of once per hour at a specified hour, for example: `0 18 * * *` diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 0aac36988d4..c5cfd63641b 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -4,7 +4,7 @@ group: Security Policies 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 --- -# Scan result policies **(ULTIMATE)** +# Scan result policies **(ULTIMATE ALL)** > Group-level scan result policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7622) in GitLab 15.6. @@ -27,6 +27,23 @@ The following video gives you an overview of GitLab scan result policies: <iframe src="https://www.youtube-nocookie.com/embed/w5I9gcUgr9U" frameborder="0" allowfullscreen> </iframe> </figure> +## Merge request with multiple pipelines + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/379108) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `multi_pipeline_scan_result_policies`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/409482) in GitLab 16.3. + +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 `multi_pipeline_scan_result_policies`. On GitLab.com, this feature is available. + +A project can have multiple pipeline types configured. A single commit can initiate multiple +pipelines, each of which may contain a security scan. + +- In GitLab 16.3 and later, the results of all completed pipelines for the latest commit in +the MR's source and target branch are evaluated and used to enforce the scan result policy. +Parent-child pipelines and on-demand DAST pipelines are not considered. +- In GitLab 16.2 and earlier, only the results of the latest completed pipeline were evaluated +when enforcing scan result policies. + ## Scan result policy editor > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8. @@ -77,6 +94,13 @@ the following sections and tables provide an alternative. ## `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. + +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. This rule enforces the defined actions based on security scan findings. | Field | Type | Required | Possible values | Description | @@ -88,6 +112,8 @@ This rule enforces the defined actions based on security scan findings. | `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | true | `info`, `unknown`, `low`, `medium`, `high`, `critical` | The severity levels for this rule to consider. | | `vulnerability_states` | `array` of `string` | true | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed`, `new_needs_triage`, `new_dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br> The `new_needs_triage` option considers the status<br><br> • Detected<br><br> The `new_dismissed` option considers the status<br><br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | +| `vulnerability_attributes` | `object` | false | `{false_positive: boolean, fix_available: boolean}` | All vulnerability findings are considered by default. But filters can be applied for attributes to consider only vulnerability findings: <br><br> • With a fix available (`fix_available: true`)<br><br> • With no fix available (`fix_available: false`)<br> • That are false positive (`false_positive: true`)<br> • That are not false positive (`false_positive: false`)<br> • Or a combination of both. For example (`fix_available: true, false_positive: false`) | +| `vulnerability_age` | `object` | false | N/A | Filter pre-existing vulnerability findings by age. A vulnerability's age is calculated as the time since it was detected in the project. The criteria are `operator`, `value`, and `interval`.<br>- The `operator` criterion specifies if the age comparison used is older than (`greater_than`) or younger than (`less_than`).<br>- The `value` criterion specifies the numeric value representing the vulnerability's age.<br>- The `interval` criterion specifies the unit of measure of the vulnerability's age: `day`, `week`, `month`, or `year`.<br><br>Example: `operator: greater_than`, `value: 30`, `interval: day`. | ## `license_finding` rule type @@ -150,6 +176,9 @@ scan_result_policy: - critical vulnerability_states: - newly_detected + vulnerability_attributes: + false_positive: true + fix_available: true actions: - type: require_approval approvals_required: 1 @@ -169,12 +198,14 @@ scan_result_policy: - low - unknown vulnerability_states: - - newly_detected + - detected + vulnerability_age: + operator: greater_than + value: 30 + interval: day actions: - type: require_approval approvals_required: 1 - user_approvers: - - sam.white role_approvers: - owner ``` @@ -183,8 +214,8 @@ In this example: - Every MR that contains new `critical` vulnerabilities identified by container scanning requires one approval from `alberto.dare`. -- Every MR that contains more than one new `low` or `unknown` vulnerability identified by container - scanning requires one approval from `sam.white`. +- Every MR that contains more than one preexisting `low` or `unknown` vulnerability older than 30 days identified by + container scanning requires one approval from a project member with the Owner role. ## Example for Scan Result Policy editor diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index fecadaa737d..832ad100701 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,7 +4,7 @@ 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 analyzers **(FREE)** +# SAST analyzers **(FREE ALL)** > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. @@ -141,7 +141,7 @@ To preview the upcoming changes to the CI/CD configuration in GitLab 15.3 or ear template: 'Jobs/SAST.latest.gitlab-ci.yaml' ``` - - On a Self-Managed instance, download the template from GitLab.com: + - On a self-managed instance, download the template from GitLab.com: ```yaml include: diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 385c5ffbae1..4ae8f1c4f8b 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -4,12 +4,13 @@ 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 --- -# Customize rulesets **(ULTIMATE)** +# 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 > 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. 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: @@ -161,7 +162,7 @@ they're not explicitly stored in the configuration file. [[semgrep.passthrough]] type = "git" value = "$GITURL" - ref = "refs/heads/main" + ref = "main" ``` ### The `[[$analyzer.ruleset]]` section @@ -293,7 +294,7 @@ The amount of data generated by a single passthrough is limited to 1 MB. | `type` | All | One of `file`, `raw`, `git` or `url`. | | `target` | All | The target file to contain the data written by the passthrough evaluation. If empty, a random filename is used. | | `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. The `git` type only supports `overwrite`. (Default: `overwrite`) | -| `ref` | `type = "git"` | Contains the name of the branch or the SHA to pull. When using a branch name, specify it in the form `refs/heads/<branch>`, not `refs/remotes/<remote_name>/<branch>`. | +| `ref` | `type = "git"` | Contains the name of the branch, tag, or the SHA to pull | | `subdir` | `type = "git"` | Used to select a subdirectory of the Git repository as the configuration source. | | `value` | All | For the `file`, `url`, and `git` types, defines the location of the file or Git repository. For the `raw` type, contains the inline configuration. | | `validator` | All | Used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target file after the evaluation of a passthrough. | @@ -445,7 +446,7 @@ that's written to the `/sgrules` directory within the container. A Different passthrough types are demonstrated in this example: -- Two `git` passthroughs, the first pulling `refs/heads/test` from the +- Two `git` passthroughs, the first pulling `develop` branch from the `myrules` Git repository, and the second pulling revision `97f7686` from the `sast-rules` repository, and considering only files in the `go` subdirectory. @@ -470,7 +471,7 @@ Afterwards, Semgrep is invoked with the final configuration located under [[semgrep.passthrough]] type = "git" value = "https://gitlab.com/user/myrules.git" - ref = "refs/heads/test" + ref = "develop" [[semgrep.passthrough]] type = "git" diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index a9bc331ae7b..717608274e5 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -4,9 +4,7 @@ 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 --- -# Static Application Security Testing (SAST) **(FREE)** - -> All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. +# Static Application Security Testing (SAST) **(FREE ALL)** NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -27,31 +25,11 @@ For more details, see the [Summary of features per tier](#summary-of-features-pe  -The results are sorted by the priority of the vulnerability: - -<!-- vale gitlab.SubstitutionWarning = NO --> - -1. Critical -1. High -1. Medium -1. Low -1. Info -1. Unknown - -<!-- vale gitlab.SubstitutionWarning = YES --> - A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard does not show SAST results. On failure, the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). -## Use cases - -- Your code has a potentially dangerous attribute in a class, or unsafe code - that can lead to unintended code execution. -- Your application is vulnerable to cross-site scripting (XSS) attacks that can - be leveraged to unauthorized access to session data. - ## Requirements SAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. @@ -66,7 +44,7 @@ GitLab SAST analyzers don't support running on Windows or on any CPU architectur WARNING: If you use your own runners, make sure the Docker version installed -is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +is **not** `19.03.0`. See [troubleshooting information](troubleshooting.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks @@ -120,8 +98,6 @@ and the [Maven wrapper](https://github.com/takari/maven-wrapper). However, SpotB ## Multi-project support -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4895) in GitLab 13.7. - GitLab SAST can scan repositories that contain multiple projects. The following analyzers have multi-project support: @@ -143,7 +119,7 @@ The following analyzers have multi-project support: Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). -## False positive detection **(ULTIMATE)** +## False positive detection **(ULTIMATE ALL)** > - Introduced for Ruby in GitLab 14.2. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378622) for Go in GitLab 15.8. @@ -158,7 +134,7 @@ False positive detection is available in a subset of the [supported languages](#  -## Advanced vulnerability tracking **(ULTIMATE)** +## Advanced vulnerability tracking **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5144) in GitLab 14.2. @@ -171,11 +147,12 @@ GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately Advanced vulnerability tracking is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): -- C, in the Semgrep-based analyzer only +- C, in the Semgrep-based and Flawfinder analyzers +- 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 analyzer only -- JavaScript, in the Semgrep-based analyzer only +- Java, in the Semgrep-based and mobsf analyzers +- JavaScript, in the Semgrep-based and NodeJS-Scan analyzers - Python, in the Semgrep-based analyzer only - Ruby, in the Brakeman-based analyzer @@ -290,7 +267,7 @@ When downloading, you always receive the most recent SAST artifact available. You can enable and configure SAST by using the UI, either with the default settings or with customizations. The method you can use depends on your GitLab license tier. -#### Configure SAST with customizations **(ULTIMATE)** +#### Configure SAST with customizations **(ULTIMATE ALL)** > [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410013) individual SAST analyzers configuration options from the UI in GitLab 16.2. @@ -316,8 +293,6 @@ Pipelines now include a SAST job. #### Configure SAST with default settings only -> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 - NOTE: The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration file. If you have a complex GitLab configuration file it may not be parsed @@ -334,11 +309,7 @@ Pipelines now include a SAST job. ### Overriding SAST jobs -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. - -To override a job definition, (for example, change properties like `variables` or `dependencies`), +To override a job definition, (for example, change properties like `variables`, `dependencies`, or [`rules`](../../../ci/yaml/index.md#rules)), declare a job with the same name as the SAST job to override. Place this new job after the template inclusion and specify any additional keys under it. For example, this enables `FAIL_NEVER` for the `spotbugs` analyzer: @@ -580,8 +551,7 @@ Some analyzers can be customized with CI/CD variables. | `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | | `SAST_GOSEC_CONFIG` | Gosec | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328301)** in GitLab 14.0 - use custom rulesets instead. Path to configuration for Gosec (optional). | | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SAST_DISABLE_BABEL` | NodeJsScan | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64025)** in GitLab 13.5 | -| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://semgrep.dev). Default: `true`. Introduced in GitLab 14.0 from the [confidential issue](../../project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | +| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://semgrep.dev). Default: `true`. Introduced in GitLab 14.0. GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | | `SAST_SCANNER_ALLOWED_CLI_OPTS` | Semgrep | CLI options (arguments with value, or flags) that are passed to the underlying security scanner when running scan operation. Only a limited set of [options](#security-scanner-configuration) are accepted. Separate a CLI option and its value using either a blank space or equals (`=`) character. For example: `name1 value1` or `name1=value1`. Multiple options must be separated by blank spaces. For example: `name1 value1 name2 value2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368565) in GitLab 15.3. | #### Security scanner configuration @@ -610,12 +580,6 @@ all [custom variables](../../../ci/variables/index.md#define-a-cicd-variable-in- to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -NOTE: -In [GitLab 13.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/220540), -variables whose names started with the following prefixes are **not** propagated to either the -analyzer containers or SAST Docker container: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, -`OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. - ### Experimental features You can receive early access to experimental features. Experimental features might be added, @@ -624,8 +588,11 @@ removed, or promoted to regular features at any time. Experimental features available are: - Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -- Disable the following rules in the [Semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) that are known to cause a high rate of false positives: - - [`eslint.detect-object-injection`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/6c4764567d9854f5e4a4a35dacf5a68def7fb4c1/rules/eslint.yml#L751-773) + +These features were previously experimental, but are now generally available: + +- Disable the [`eslint.detect-object-injection`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/6c4764567d9854f5e4a4a35dacf5a68def7fb4c1/rules/eslint.yml#L751-773) in the [Semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) because it causes a high rate of false positives. + - This rule was [disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/373920) in 15.10. #### Enable experimental features @@ -751,156 +718,3 @@ documentation for instructions. ## Running SAST in SELinux By default SAST analyzers are supported in GitLab instances hosted on SELinux. Adding a `before_script` in an [overridden SAST job](#overriding-sast-jobs) may not work as runners hosted on SELinux have restricted permissions. - -## Troubleshooting - -### Debug-level logging - -Debug-level logging can help when troubleshooting. For details, see -[debug-level logging](../index.md#debug-level-logging). - -### Pipeline errors related to changes in the GitLab-managed CI/CD template - -The [GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: - -- See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. -- Experience another type of unexpected issue with your CI/CD pipeline configuration. - -If you're experiencing a job failure or seeing a SAST-related `yaml invalid` pipeline status, you can temporarily revert to an older version of the template so your pipelines keep working while you investigate the issue. To use an older version of the template, change the existing `include` statement in your CI/CD YAML file to refer to a specific template version, such as `v15.3.3-ee`: - -```yaml -include: - remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml' -``` - -If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. - -We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-in-your-cicd-yaml) as soon as possible. - -### Errors in a specific analyzer job - -GitLab SAST [analyzers](analyzers.md) are released as container images. -If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). - -Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. - -### `exec /bin/sh: exec format error` message in job log - -GitLab SAST analyzers [only support](#requirements) running on the `amd64` CPU architecture. -This message indicates that the job is being run on a different architecture, such as `arm`. - -### `Error response from daemon: error processing tar file: docker-tar: relocation error` - -This error occurs when the Docker version that runs the SAST job is `19.03.0`. -Consider updating to Docker `19.03.1` or greater. Older versions are not -affected. Read more in -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). - -### Getting warning message `gl-sast-report.json: no matching files` - -For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). - -### Error: `sast is used for configuration only, and its script should not be executed` - -For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). - -### Limitation when using rules:exists - -The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -uses the `rules:exists` parameter. For performance reasons, a maximum number of matches are made -against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists` -parameter returns `true`. Depending on the number of files in your repository, a SAST job might be -triggered even if the scanner doesn't support your project. For more details about this issue, see -the [`rules:exists` documentation](../../../ci/yaml/index.md#rulesexists). - -### SpotBugs UTF-8 unmappable character errors - -These errors occur when UTF-8 encoding isn't enabled on a SpotBugs build and there are UTF-8 -characters in the source code. To fix this error, enable UTF-8 for your project's build tool. - -For Gradle builds, add the following to your `build.gradle` file: - -```gradle -compileJava.options.encoding = 'UTF-8' -tasks.withType(JavaCompile) { - options.encoding = 'UTF-8' -} -``` - -For Maven builds, add the following to your `pom.xml` file: - -```xml -<properties> - <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> -</properties> -``` - -### SpotBugs Error: `Project couldn't be built` - -If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). - -The solution is to use [pre-compilation](#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. - -### Flawfinder encoding error - -This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. - -### Semgrep slowness, unexpected results, or other errors - -If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/semgrep-ci/#troubleshooting-gitlab-sast). - -### SAST job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` - -Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: - -- Disabled by default in GitLab 13.0 and later. -- Unsupported from GitLab 13.4 and later. - -Several workarounds are available. From GitLab version 13.0 and later, you must not use -Docker-in-Docker. - -#### Workaround 1: Pin analyzer versions (GitLab 12.1 and earlier) - -Set the following variables for the SAST job. This pins the analyzer versions to the last known -working version, allowing SAST with Docker-in-Docker to complete as it did previously: - -```yaml -sast: - variables: - SAST_DEFAULT_ANALYZERS: "" - SAST_ANALYZER_IMAGES: "registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2.9.6, registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2.10.0, registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2.11.1, registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2.14.0, registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2.9.1, registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2.9.0, registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3.12.0, registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2.13.0, registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2.8.0, registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2.13.6, registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2.4.0" -``` - -Remove any analyzers you don't need from the `SAST_ANALYZER_IMAGES` list. Keep -`SAST_DEFAULT_ANALYZERS` set to an empty string `""`. - -#### Workaround 2: Disable Docker-in-Docker for SAST and Dependency Scanning (GitLab 12.3 and later) - -Disable Docker-in-Docker for SAST. Individual `<analyzer-name>-sast` jobs are created for each -analyzer that runs in your CI/CD pipeline. - -```yaml -include: - - template: SAST.gitlab-ci.yml - -variables: - SAST_DISABLE_DIND: "true" -``` - -#### Workaround 3: Upgrade to GitLab 13.x and use the defaults - -From GitLab 13.0, SAST defaults to not using Docker-in-Docker. In GitLab 13.4 and later, SAST using -Docker-in-Docker is [no longer supported](https://gitlab.com/gitlab-org/gitlab/-/issues/220540). -If you have this problem on GitLab 13.x and later, you have customized your SAST job to -use Docker-in-Docker. To resolve this, comment out any customizations you've made to -your SAST CI job definition and [follow the documentation](index.md#configuration) -to reconfigure, using the new and improved job definition default values. - -```yaml -include: - - template: Security/SAST.gitlab-ci.yml -``` - -### MobSF job fails with error message `Reading from Info.plist` - -This error happens when `Info.plist` file is missing a `CFBundleIdentifier` key and string value. diff --git a/doc/user/application_security/sast/troubleshooting.md b/doc/user/application_security/sast/troubleshooting.md new file mode 100644 index 00000000000..34a2a3d01af --- /dev/null +++ b/doc/user/application_security/sast/troubleshooting.md @@ -0,0 +1,102 @@ +--- +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 +--- + +# Troubleshooting SAST **(FREE ALL)** + +## Debug-level logging + +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). + +## Pipeline errors related to changes in the GitLab-managed CI/CD template + +The [GitLab-managed SAST CI/CD template](index.md#configure-sast-in-your-cicd-yaml) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: + +- See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. +- Experience another type of unexpected issue with your CI/CD pipeline configuration. + +If you're experiencing a job failure or seeing a SAST-related `yaml invalid` pipeline status, you can temporarily revert to an older version of the template so your pipelines keep working while you investigate the issue. To use an older version of the template, change the existing `include` statement in your CI/CD YAML file to refer to a specific template version, such as `v15.3.3-ee`: + +```yaml +include: + remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml' +``` + +If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. + +We recommend that you only use this solution temporarily and that you return to [the standard template](index.md#configure-sast-in-your-cicd-yaml) as soon as possible. + +## Errors in a specific analyzer job + +GitLab SAST [analyzers](analyzers.md) are released as container images. +If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](index.md#configure-sast-in-your-cicd-yaml) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](index.md#pinning-to-minor-image-version). + +Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. + +## `exec /bin/sh: exec format error` message in job log + +GitLab SAST analyzers [only support](index.md#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. + +## `Error response from daemon: error processing tar file: docker-tar: relocation error` + +This error occurs when the Docker version that runs the SAST job is `19.03.0`. +Consider updating to Docker `19.03.1` or greater. Older versions are not +affected. Read more in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +## Getting warning message `gl-sast-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). + +## Error: `sast is used for configuration only, and its script should not be executed` + +For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +## Limitation when using rules:exists + +The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +uses the `rules:exists` parameter. For performance reasons, a maximum number of matches are made +against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists` +parameter returns `true`. Depending on the number of files in your repository, a SAST job might be +triggered even if the scanner doesn't support your project. For more details about this issue, see +the [`rules:exists` documentation](../../../ci/yaml/index.md#rulesexists). + +## SpotBugs UTF-8 unmappable character errors + +These errors occur when UTF-8 encoding isn't enabled on a SpotBugs build and there are UTF-8 +characters in the source code. To fix this error, enable UTF-8 for your project's build tool. + +For Gradle builds, add the following to your `build.gradle` file: + +```gradle +compileJava.options.encoding = 'UTF-8' +tasks.withType(JavaCompile) { + options.encoding = 'UTF-8' +} +``` + +For Maven builds, add the following to your `pom.xml` file: + +```xml +<properties> + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> +</properties> +``` + +## SpotBugs Error: `Project couldn't be built` + +If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). + +The solution is to use [pre-compilation](index.md#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. + +## Flawfinder encoding error + +This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. + +## Semgrep slowness, unexpected results, or other errors + +If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/semgrep-ci/#troubleshooting-gitlab-sast). diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md index 66ed2f10a3c..1a5ab913b29 100644 --- a/doc/user/application_security/secret_detection/automatic_response.md +++ b/doc/user/application_security/secret_detection/automatic_response.md @@ -4,7 +4,7 @@ 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 --- -# Automatic response to leaked secrets **(ULTIMATE)** +# Automatic response to leaked secrets **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. @@ -23,7 +23,7 @@ GitLab supports automatic response for the following types of secrets: | GitLab [Personal access tokens](../../profile/personal_access_tokens.md) | Immediately revoke token, send email to owner | ✅ | ✅ [15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) | | Amazon Web Services (AWS) [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | Notify AWS | ✅ | ⚙ | | Google Cloud [service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys), [API keys](https://cloud.google.com/docs/authentication/api-keys), and [OAuth client secrets](https://support.google.com/cloud/answer/6158849#rotate-client-secret) | Notify Google Cloud | ✅ | ⚙ | -| Postman [API keys](https://learning.postman.com/docs/developer/postman-api/authentication/) | Notify Postman; Postman emails the key owner | ✅ | ⚙ | +| Postman [API keys](https://learning.postman.com/docs/developer/postman-api/authentication/) | Notify Postman; Postman [notifies the key owner](https://learning.postman.com/docs/administration/token-scanner/#protecting-postman-api-keys-in-gitlab) | ✅ | ⚙ | **Component legend** diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index ea2a66c7cc7..10e8356de16 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -4,7 +4,7 @@ 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 --- -# Secret Detection **(FREE)** +# Secret Detection **(FREE ALL)** > - In GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast/index.md#configuration) > into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then @@ -137,7 +137,7 @@ shared runners on GitLab.com, this is enabled by default. - Windows Runners are not supported. - CPU architectures other than amd64 are not supported. - If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See - [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) + [troubleshooting information](../sast/troubleshooting.md#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. - GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. @@ -335,7 +335,7 @@ pipeline. To enable full history Secret Detection, set the variable `SECRET_DETECTION_HISTORIC_SCAN` to `true` in your `.gitlab-ci.yml` file. -## Custom rulesets **(ULTIMATE)** +## 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. @@ -350,6 +350,7 @@ The following customization options can be used separately, or in combination: - [Disable predefined rules](#disable-predefined-analyzer-rules). - [Override predefined rules](#override-predefined-analyzer-rules). - [Synthesize a custom configuration](#synthesize-a-custom-configuration). +- [Specify a remote configuration file](#specify-a-remote-configuration-file). ### Disable predefined analyzer rules @@ -496,7 +497,7 @@ path = "/gitleaks.toml" ] ``` -## Specify a remote configuration file +### Specify a remote configuration file Projects can be configured with a [CI/CD variable](../../../ci/variables/index.md) in order to specify a ruleset configuration outside of the current repository. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md deleted file mode 100644 index 3a6cf7f7e37..00000000000 --- a/doc/user/application_security/secret_detection/post_processing.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'automatic_response.md' -remove_date: '2023-08-08' ---- - -This document was moved to [another location](automatic_response.md). - -<!-- This redirect file can be deleted after 2023-08-08. --> -<!-- 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/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index 8dd1168a0d9..0b028f6936d 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -4,7 +4,7 @@ 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 --- -# Secure your application **(FREE)** +# Secure your application **(FREE ALL)** GitLab can check your applications for security vulnerabilities. diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index e28c06236aa..b6d95e53227 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,7 +5,7 @@ group: Threat Insights 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 Security Dashboards and Security Center **(ULTIMATE)** +# GitLab Security Dashboards and Security Center **(ULTIMATE ALL)** You can use Security Dashboards to view trends about vulnerabilities detected by [security scanners](../index.md#application-coverage). diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index df103976901..5c2dbd8d728 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Secure and Govern glossary **(FREE)** +# Secure and Govern glossary **(FREE ALL)** The glossary of terms aims to achieve the following: diff --git a/doc/user/application_security/vulnerabilities/img/explain_this_vulnerability_beta_v16_3.png b/doc/user/application_security/vulnerabilities/img/explain_this_vulnerability_beta_v16_3.png Binary files differnew file mode 100644 index 00000000000..55266babbf2 --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/explain_this_vulnerability_beta_v16_3.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 1950c620627..fa0027754ad 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -4,7 +4,7 @@ group: Threat Insights 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 --- -# Vulnerability Page **(ULTIMATE)** +# Vulnerability Page **(ULTIMATE ALL)** Each vulnerability in a project has a vulnerability page containing details of the vulnerability, including: @@ -24,6 +24,59 @@ 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)** + +> - [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. + +GitLab can help you with a vulnerability by using a large language model to: + +- Summarize the vulnerability. +- Help developers and security analysts to understand the vulnerability, how it could be exploited, and how to fix it. +- Provide a suggested mitigation. + +### Explain a vulnerability + +Use the explain this vulnerability feature to better understand a vulnerability and its possible +mitigation. + +Prerequisites: + +- You must have the GitLab Ultimate subscription tier. +- 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). + +To explain the vulnerability: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to 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. +1. At the bottom of the vulnerability's page, select **Try it out**. + +The response is shown on the right side of the page. + + + +On GitLab.com this feature is available. By default, it is powered by Google's `text-bison-001` +model. In the event of degraded performance with that model, the feature instead uses Anthropic's +`claude` model. + +We cannot guarantee that the large language model produces results that are correct. Use the +explanation with caution. + +### Data shared with third-party AI APIs + +The following data is shared with third-party AI APIs: + +- Vulnerability title (which might contain the filename, depending on which scanner is used). +- Vulnerability identifiers. +- Code block, but only if the "Send code with prompt" checkbox is selected (single and multi-line as instructed by the vulnerability + record). +- Filename. + ## Vulnerability status values A vulnerability's status can be: diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 9553d15bbe9..31946d414a2 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# Vulnerability severity levels **(ULTIMATE)** +# Vulnerability severity levels **(ULTIMATE ALL)** GitLab vulnerability analyzers attempt to return vulnerability severity level values whenever possible. The following is a list of available GitLab vulnerability severity levels, ranked from @@ -22,7 +22,7 @@ GitLab analyzers make an effort to fit the severity descriptions below, but they ## Critical severity -Vulnerabilities identified at the Critical Severity level should be investigated immediately. Vulnerabilities at this level assume exploitation of the flaw could lead to full system or data compromise. Examples of critical severity flaws are Command/Code Injection and SQL Injection. Typically these flaws are rated with CVSS 3.1 between 9.0-10.0. +Vulnerabilities identified at the Critical Severity level should be investigated immediately. Vulnerabilities at this level assume exploitation of the flaw could lead to full system or data compromise. Examples of critical severity flaws are Command/Code Injection and SQL Injection. Typically these flaws are rated with CVSS 3.1 between 9.0-10.0. ## High severity diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 78f8bbdb0c3..46ce3173ee7 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# Vulnerability Report **(ULTIMATE)** +# Vulnerability Report **(ULTIMATE ALL)** The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. The scan results from a @@ -48,6 +48,9 @@ At the project level, the Vulnerability Report also contains: - The number of failures that occurred in the most recent pipeline. Select the failure notification to view the **Failed jobs** tab of the pipeline's page. +When vulnerabilities originate from a multi-project pipeline setup, +this page displays the vulnerabilities that originate from the selected project. + ### View the project-level vulnerability report To view the project-level vulnerability report: diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index a53e0a8970b..7a414e9a4ae 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -29,6 +29,8 @@ the [Vulnerability Report](index.md), which contains cumulative results of all s [security widget](../index.md#view-security-scan-information-in-merge-requests), which combines the branch results with cumulative results. +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. + Before GitLab displays results, the vulnerability findings in all pipeline reports are [deduplicated](#deduplication-process). ## Scan details diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index d2041083d36..b481c0458aa 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -4,7 +4,7 @@ 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 --- -# AsciiDoc **(FREE)** +# AsciiDoc **(FREE ALL)** GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference. diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index aaba0225653..a7c58b4d2a8 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Emoji reactions **(FREE)** +# Emoji reactions **(FREE ALL)** > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0. > - Reacting with emoji on work items (such as tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393599) in GitLab 16.0. diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index a0b42101dd5..260263632c5 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.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 --- -# Using GitLab CI/CD with a Kubernetes cluster **(FREE)** +# Using GitLab CI/CD with a Kubernetes cluster **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. > - The pre-configured variable `$KUBECONFIG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. @@ -196,7 +196,7 @@ To configure your client, do one of the following: - Place the certificates in an appropriate location in the job container by updating the container image or mounting via the runner. - Not recommended. Configure the Kubernetes client with `--insecure-skip-tls-verify=true`. -## Restrict project and group access by using impersonation **(PREMIUM)** +## Restrict project and group access by using impersonation **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/357934) in GitLab 15.5 to add impersonation support for environment tiers. @@ -300,7 +300,7 @@ The identity can be specified with the following keys: See the [official Kubernetes documentation for details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). -## Restrict project and group access to specific environments **(FREE)** +## Restrict project and group access to specific environments **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343885) in GitLab 15.7. diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index aff78ed477b..d79d32a1234 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.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 --- -# Using GitOps with a Kubernetes cluster **(FREE)** +# Using GitOps with a Kubernetes cluster **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. @@ -78,6 +78,7 @@ For additional repository structure recommendations, see the [Flux documentation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `notify_kas_on_git_push`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126527) in GitLab 16.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410429) in GitLab 16.3. Usually, the Flux source controller reconciles Git repositories at configured intervals. This can cause delays between a `git push` and the reconciliation of the cluster state, and results in diff --git a/doc/user/clusters/agent/gitops/agent.md b/doc/user/clusters/agent/gitops/agent.md index 07ed2b3a691..a4e83916acb 100644 --- a/doc/user/clusters/agent/gitops/agent.md +++ b/doc/user/clusters/agent/gitops/agent.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 --- -# Using GitOps with the agent for Kubernetes (deprecated) **(FREE)** +# Using GitOps with the agent for Kubernetes (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md index a5bc3b153fe..02eea3300af 100644 --- a/doc/user/clusters/agent/gitops/example_repository_structure.md +++ b/doc/user/clusters/agent/gitops/example_repository_structure.md @@ -1,78 +1,179 @@ --- stage: Deploy group: Environments -info: An example of how to structure a repository for GitOps deployments +info: A tutorial for deploying a GitLab repository using Flux --- -# Example GitOps repository structure **(FREE)** +# Tutorial: Deploy a Git repository using Flux **(FREE ALL)** -This page describes an example structure for a project that builds and deploys an application -to a Kubernetes cluster with [GitOps](https://about.gitlab.com/topics/gitops) and the -[GitLab agent for Kubernetes](../../agent/gitops.md). +In this tutorial, you'll create a GitLab project that builds and deploys an application +to a Kubernetes cluster using Flux. You'll set up a sample manifest project, configure it to +push manifests to a deployment branch, and configure Flux to sync the deployment branch. With this +setup, you can run additional steps in GitLab pipelines before Flux picks up the changes +from the repository. + +This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md). + +To set up a repository for GitOps deployments: + +1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) +1. [Create a deployment branch](#create-a-deployment-branch) +1. [Configure GitLab CI/CD to push to your branch](#configure-gitlab-cicd-to-push-to-your-branch) +1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests) +1. [Verify your configuration](#verify-your-configuration) + +Prerequisites: + +- You have a Flux repository connected to a Kubernetes cluster. + If you're starting from scratch, see [Set up Flux for GitOps](flux_tutorial.md). -You can find an example project that uses this structure -[in this GitLab repository](https://gitlab.com/tigerwnz/minimal-gitops-app). You can use the example project -as a starting point to create your own deployment project. +## Create the Kubernetes manifest repository -## Deployment workflow +First, create a repository for your Kubernetes manifests: -The default branch is the single source of truth for your application and the -Kubernetes manifests that deploy it. To be reflected in a Kubernetes cluster, -a code or configuration change must exist in the default branch. +1. In GitLab, create a new repository called `web-app-manifests`. +1. In `web-app-manifests`, add a file named `src/nginx-deployment.yaml` with the following contents: -A GitLab agent for Kubernetes is installed in every Kubernetes cluster. The agent -is configured to sync manifests from a corresponding branch in the repository. -These branches represent the state of each cluster, and contain only commits that -exist in the default branch. - -Changes are deployed by merging the default branch into the branch of a cluster. -The agent that watches the branch picks up the change and syncs it to the cluster. - -For the actual deployment, the example project uses the GitLab agent for Kubernetes, -but you can also use other GitOps tools. - -### Review apps - -Ephemeral environments such as [review apps](../../../../ci/review_apps/index.md) -are deployed differently. Their configuration does not exist on the default branch, -and the changes are not meant to be deployed to a permanent environment. Review app -manifests are generated and deployed in a merge request feature branch, which is removed -when the MR is merged. - -## Example deployment - -The example project deploys to two permanent environments, staging and production, -which each have a dedicated Kubernetes cluster. A third cluster is used for ephemeral -review apps. - -Each cluster has a corresponding branch that represents the current state of the cluster: -`_gitlab/agents/staging`, `_gitlab/agents/production` and `_gitlab/agents/review`. Each branch is -[protected](../../../../user/project/protected_branches.md) and -a [project access token](../../../../user/project/settings/project_access_tokens.md) -is created for each branch with a configuration that allows only the corresponding token to push to the branch. -This ensures that environment branches are updated only through the configured process. - -Deployment branches are updated by CI/CD jobs. The access token that allows pushing to each -branch is configured as a [CI/CD variable](../../../../ci/variables/index.md). These variables -are protected, and only available to pipelines running on a protected branch. -The CI/CD job merges the default branch `main` into the deployment branch, and pushes -the deployment branch back to the repository using the provided token. To preserve the -commit history between both branches, the CI/CD job uses a fast-forward merge. - -Each cluster has an agent for Kubernetes, and each agent is configured to -sync manifests from the branch corresponding to its cluster. -In your own project, you can different GitOps tool like Flux, or use the same configuration to deploy -to virtual machines with GitLab CI/CD. - -### Application changes - -The example project follows this process to deploy an application change: - -1. A new feature branch is created with the desired changes. The pipeline builds an image, - runs the test suite, and deploy the changes to a review app in the `review` cluster. -1. The feature branch is merged to `main` and the review app is removed. -1. Manifests are updated on `main` (either directly or via merge request) to point to an updated - version of the deployed image. The pipeline automatically merges `main` into the `_gitlab/agents/staging` - branch, which updates the `staging` cluster. -1. The `production` job is triggered manually, and merges `main` into the `_gitlab/agents/production` branch, - deploying to the `production` cluster. + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx + spec: + replicas: 1 + template: + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + ``` + +1. In `web-app-manifests`, add a file named `src/kustomization.yaml` with the following contents: + + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization + resources: + - nginx-deployment.yaml + commonLabels: + app: flux-branches-tutorial + ``` + +## Create a deployment branch + +Next, create a branch to reflect the current state of your cluster. + +In this workflow, the default branch is the single source of truth for your application. +To be reflected in a Kubernetes cluster, a code or configuration change must exist in the default branch. +In a later step, you'll configure CI/CD to merge changes from the default branch into the deployment branch. + +To create a deployment branch: + +1. In `web-app-manifests`, create a branch named `_gitlab/deploy/example` from the default branch. The branch name in this example is chosen to + differentiate the deployment branch from feature branches, but this is not required. You can name the deployment branch whatever you like. +1. Create a [project](../../../../user/project/settings/project_access_tokens.md), + [group](../../../../user/group/settings/group_access_tokens.md) or + [personal access token](../../../../user/profile/personal_access_tokens.md) with the `write_repository` scope. +1. Create a [CI/CD variable](../../../../ci/variables/index.md) with a token value named `DEPLOYMENT_TOKEN`. + Remember to [mask](../../../../ci/variables/index.md#mask-a-cicd-variable) the value so that it won't show in + job logs. +1. Add a rule to [protect](../../../../user/project/protected_branches.md) + your deployment branch with the following values: + + - Allowed to merge: No one. + - Allowed to push and merge: Select the token you created in the previous step, or your user if you created + a personal access token. + - Allowed to force push: Turn off the toggle. + - Require approval from code owners: Turn off the toggle. + +This configuration ensures that only the corresponding token can push to the branch. + +You've successfully created a repository with a protected deployment branch! + +## Configure GitLab CI/CD to push to your branch + +Next, you'll configure CI/CD to merge changes from the default branch to your deployment branch. + +In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/yaml/gitlab_ci_yaml.md) file with the following contents: + + ```yaml + deploy: + stage: deploy + environment: production + variables: + DEPLOYMENT_BRANCH: _gitlab/deploy/example + script: + - | + git config user.name "Deploy Example Bot" + git config user.email "test@example.com" + git fetch origin $DEPLOYMENT_BRANCH + git checkout $DEPLOYMENT_BRANCH + git merge $CI_COMMIT_SHA --ff-only + git push https://deploy:$DEPLOYMENT_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git HEAD:$DEPLOYMENT_BRANCH + resource_group: $CI_ENVIRONMENT_SLUG + ``` + +This creates a CI/CD pipeline with a single `deploy` job that: + +1. Checks out your deployment branch. +1. Merges new changes from the default branch into the deployment branch. +1. Pushes the changes to your repository with the configured token. + +## Configure Flux to sync your manifests + +Next, configure your Flux repository to sync the deployment branch in by the `web-app-manifests` repository. + +To configure, create a [`GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) resource: + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-source.yaml` + with the following contents: + + ```yaml + apiVersion: source.toolkit.fluxcd.io/v1 + kind: GitRepository + metadata: + name: web-app-manifests + namespace: flux-system + spec: + interval: 5m0s + url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-branches + ref: + branch: _gitlab/deploy/example + ``` + + You will need to substitute the `url` with the URL of your `web-app-manifests` project. + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-kustomization.yaml` + with the following contents: + + ```yaml + apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + metadata: + name: nginx-source-kustomization + namespace: flux-system + spec: + interval: 1m0s + path: ./src + prune: true + sourceRef: + kind: GitRepository + name: web-app-manifests + targetNamespace: default + ``` + + This file adds a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests in the artifact fetched from the registry. + +1. Commit the new files and push. + +## Verify your configuration + +After the pipeline completes, you should see a newly created `nginx` pod in your cluster. + +If you want to see the deployment sync again, try updating the number of replicas in the +`src/nginx-deployment.yaml` file and push to the default branch. If all is working well, the change +will sync to the cluster when the pipeline has finished. + +Congratulations! You successfully configured a project to deploy an application and synchronize your changes! diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md new file mode 100644 index 00000000000..b970c818a72 --- /dev/null +++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md @@ -0,0 +1,154 @@ +--- +stage: Deploy +group: Environments +info: A tutorial for deploying an OCI artifact using Flux +--- + +# Tutorial: Deploy an OCI artifact using Flux **(FREE ALL)** + +This tutorial teaches you how to package your Kubernetes manifests into an [OCI](https://opencontainers.org/) +artifact and deploy them to your cluster using Flux. You'll set up a sample manifest project, configure it to +store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact. With this +setup, you can run additional steps in GitLab pipelines before Flux picks up the changes +from the OCI image. + +This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md). + +To deploy an OCI artifact using Flux: + +1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) +1. [Configure the manifest repository to create an OCI artifact](#configure-the-manifest-repository-to-create-an-oci-artifact) +1. [Configure Flux to sync your artifact](#configure-flux-to-sync-your-artifact) +1. [Verify your configuration](#verify-your-configuration) + +Prerequisites: + +- You have a Flux repository connected to a Kubernetes cluster. + If you're starting from scratch, see [Set up Flux for GitOps](flux_tutorial.md). + +## Create the Kubernetes manifest repository + +First, create a repository for your Kubernetes manifests: + +1. In GitLab, create a new repository called `web-app-manifests`. +1. In `web-app-manifests`, add a file named `src/nginx-deployment.yaml` with the following contents: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx + spec: + replicas: 1 + template: + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + ``` + +1. In `web-app-manifests`, add a file named `src/kustomization.yaml` with the following contents: + + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization + resources: + - nginx-deployment.yaml + commonLabels: + app: flux-oci-tutorial + ``` + +## Configure the manifest repository to create an OCI artifact + +Next, configure [GitLab CI/CD](../../../../ci/index.md) to package your manifests into an OCI artifact, +and push the artifact to the [GitLab Container Registry](../../../packages/container_registry/index.md): + +1. In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/yaml/gitlab_ci_yaml.md) file with the following contents: + + ```yaml + package: + stage: deploy + image: + name: fluxcd/flux-cli:v2.0.0-rc.1 + entrypoint: [""] + script: + - mkdir -p manifests + - kubectl kustomize ./src --output ./manifests + - | + flux push artifact oci://$CI_REGISTRY_IMAGE:latest \ + --path="./manifests" \ + --source="$CI_REPOSITORY_URL" \ + --revision="$CI_COMMIT_SHORT_SHA" \ + --creds="$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \ + --annotations="org.opencontainers.image.url=$CI_PROJECT_URL" \ + --annotations="org.opencontainers.image.title=$CI_PROJECT_NAME" \ + --annotations="com.gitlab.job.id=$CI_JOB_ID" \ + --annotations="com.gitlab.job.url=$CI_JOB_URL" + ``` + + When the file is pushed to GitLab, a CI/CD pipeline with a single `package` job is created. This job: + + - Uses `kustomization.yaml` to render your final Kubernetes manifests. + - Packages your manifests into an OCI artifact. + - Pushes the OCI artifact to the Container Registry. + + After the pipeline has completed, you can check your OCI artifact with the Container Registry UI. + +## Configure Flux to sync your artifact + +Next, configure your Flux repository to sync the artifact produced by the `web-app-manifests` repository. + +To configure, create an [`OCIRepository`](https://fluxcd.io/flux/components/source/ocirepositories/) resource: + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-source.yaml` + with the following contents: + + ```yaml + apiVersion: source.toolkit.fluxcd.io/v1 + kind: OCIRepository + metadata: + name: web-app-manifests + namespace: flux-system + spec: + interval: 1m0s + url: oci://registry.gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-oci + ref: + tag: latest + ``` + + You will need to substitute the `url` with the URL of your `web-app-manifests` project's container registry. + +1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-kustomization.yaml` + with the following contents: + + ```yaml + apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + metadata: + name: nginx-source-kustomization + namespace: flux-system + spec: + interval: 1m0s + path: ./ + prune: true + sourceRef: + kind: OCIRepository + name: web-app-manifests + targetNamespace: default + ``` + + This file adds a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests in the artifact fetched from the registry. + +1. Commit the new files and push. + +## Verify your configuration + +You should see a newly created `nginx` pod in your cluster. + +If you want to see the deployment sync again, try updating the number of replicas in the +`src/nginx-deployment.yaml` file and push to the default branch. If all is working well, the change +should sync to the cluster when the pipeline has finished. + +Congratulations! You successfully configured a project to deploy an application and synchronize your changes! diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index 8aee0c01d65..f2d65b900f0 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -4,7 +4,7 @@ group: Environments info: A tutorial using Flux --- -# Tutorial: Set up Flux for GitOps **(FREE)** +# Tutorial: Set up Flux for GitOps **(FREE ALL)** This tutorial teaches you how to set up Flux for GitOps. You'll complete a bootstrap installation, install `agentk` in your cluster, and deploy a simple `nginx` application. @@ -83,8 +83,19 @@ You must register `agentk` before you install it in your cluster. To register `agentk`: -- Complete the steps in [Register the agent with GitLab](../install/index.md#register-the-agent-with-gitlab). - Be sure to save the agent registration token and `kas` address. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to 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**. +1. Select **Connect a cluster (agent)**. + - If you want to create a configuration with CI/CD defaults, type a name. + - If you already have an agent configuration file, select it from the list. +1. Select **Register an agent**. +1. Securely store the agent access token and `kasAddress` for later. + +The agent is registered for your project. You don't need to run any commands yet. + +In the next step, you'll use Flux to install `agentk` in your cluster. ## Install `agentk` @@ -103,10 +114,24 @@ To install `agentk`: name: gitlab ``` -1. Apply the agent registration token as a secret in the cluster: +1. Create a file called `secret.yaml` that contains your agent access token as a secret: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: gitlab-agent-token + type: Opaque + stringData: + values.yaml: |- + config: + token: "<your-token-here>" + ``` + +1. Apply `secret.yaml` to your cluster: ```shell - kubectl create secret generic gitlab-agent-token -n gitlab --from-literal=token=YOUR-TOKEN-HERE + kubectl apply -f secret.yaml -n gitlab ``` Although this step does not follow GitOps principles, it simplifies configuration for new Flux users. @@ -147,8 +172,11 @@ To install `agentk`: interval: 1h0m0s values: config: - kasAddress: "wss://kas.gitlab.example.com" - secretName: "gitlab-agent-token" + kasAddress: "wss://kas.gitlab.com" + valuesFrom: + - kind: Secret + name: gitlab-agent-token + valuesKey: values.yaml ``` 1. To verify that `agentk` is installed and running in the cluster, run the following command: diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index a0d6e0d415d..140ac060dc7 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -63,9 +63,9 @@ GitLab in a Kubernetes cluster, you might need a different version of Kubernetes You can upgrade your Kubernetes version to a supported version at any time: +- 1.27 (support ends on July 22, 2024 or when 1.30 becomes supported) - 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) -- 1.24 (support ends on July 22, 2023 or when 1.27 becomes supported) GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time. @@ -80,6 +80,18 @@ Some GitLab features might work on versions not listed here. [This epic](https:/ Read about how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration. +## Agent connection + +The agent opens a bidirectional channel to KAS for communication. +This channel is used for all communication between the agent and KAS: + +- Each agent can maintain up to 500 logical gRPC streams, including active and idle streams. +- The number of TCP connections used by the gRPC streams is determined by gRPC itself. +- Each connection has a maximum lifetime of two hours, with a one-hour grace period. + - A proxy in front of KAS might influence the maximum lifetime of connections. On GitLab.com, this is [two hours](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/-/blob/68df3484087f0af368d074215e17056d8ab69f1c/attributes/default.rb#L217). The grace period is 50% of the maximum lifetime. + +For detailed information about channel routing, see [Routing KAS requests in the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kas_request_routing.md). + ## Related topics - [GitOps workflow](gitops.md) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index c847eaff13f..75571d1a4f5 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.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 --- -# Installing the agent for Kubernetes **(FREE)** +# Installing the agent for Kubernetes **(FREE ALL)** > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index eddc6ef3e16..c01b1337aca 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -239,3 +239,23 @@ Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): uncl ``` This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#supported-kubernetes-versions-for-gitlab-features). + +## `GitLab Agent Server: Unauthorized` error on Dashboard for Kubernetes + +An error like `GitLab Agent Server: Unauthorized. Trace ID: <...>` +on the [Dashboard for Kubernetes](../../../ci/environments/kubernetes_dashboard.md) page +might be caused by one of the following: + +- The `user_access` entry in the agent configuration file doesn't exist or is wrong. + To resolve, see [Grant users Kubernetes access](user_access.md). +- There are multiple [`_gitlab_kas` cookies](../../../administration/clusters/kas.md#kubernetes-api-proxy-cookie) + in the browser and sent to KAS. The most likely cause is multiple GitLab instances hosted + on the same site. + + For example, `gitlab.com` set a `_gitlab_kas` cookie targeted for `kas.gitlab.com`, + but the cookie is also sent to `kas.staging.gitlab.com`, which causes the error on `staging.gitlab.com`. + + To temporarily resolve, delete the `_gitlab_kas` cookie for `gitlab.com` from the browser cookie store. + [Issue 418998](https://gitlab.com/gitlab-org/gitlab/-/issues/418998) proposes a fix for this known issue. +- GitLab and KAS run on different sites. For example, GitLab on `gitlab.example.com` and KAS on `kas.example.com`. + GitLab does not support this use case. For details, see [issue 416436](https://gitlab.com/gitlab-org/gitlab/-/issues/416436). diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index 7e04091c940..a5989d823f6 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)** +# Grant users Kubernetes access (Beta) **(FREE ALL)** > - [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. @@ -15,6 +15,11 @@ of a specific project or group. Granting access also activates the Dashboard for Kubernetes for a project or group. +For self-managed instances, make sure you either: + +- Host your GitLab instance and [KAS](../../../administration/clusters/kas.md) on the same domain. +- Host KAS on a subdomain of GitLab. For example, GitLab on `gitlab.com` and KAS on `kas.gitlab.com`. + ## Configure Kubernetes access Configure access when you want to grant users access @@ -51,7 +56,7 @@ user_access: - id: group-3/subgroup ``` -## Configure access with user impersonation **(PREMIUM)** +## Configure access with user impersonation **(PREMIUM ALL)** You can grant access to a Kubernetes cluster and transform requests into impersonation requests for authenticated users. diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 74676e31d22..a967ec9ea24 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -4,7 +4,7 @@ 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 --- -# Operational Container Scanning **(ULTIMATE)** +# Operational Container Scanning **(ULTIMATE ALL)** > - [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. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index e8fb399d1b0..08e1021f886 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.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 --- -# Working with the agent for Kubernetes **(FREE)** +# Working with the agent for Kubernetes **(FREE ALL)** Use the following tasks when working with the agent for Kubernetes. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 6ed0f08c4a7..a155dcf4a3c 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Cluster cost management (removed) **(ULTIMATE)** +# 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/environments.md b/doc/user/clusters/environments.md index fa56dc320be..4a6fa8d4862 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.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 --- -# Cluster Environments (deprecated) **(PREMIUM)** +# Cluster Environments (deprecated) **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in GitLab 12.3 for group-level clusters. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in GitLab 12.4 for instance-level clusters. diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 3076730b10f..0f389b94a33 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Cluster integrations (removed) **(FREE)** +# 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 9f769c6535c..3341074f54d 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.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 --- -# Cluster management project (deprecated) **(FREE)** +# Cluster management project (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index f6bcff0481a..f4f42f4dc27 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.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 --- -# Manage cluster applications **(FREE)** +# Manage cluster applications **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. > - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index fde8e455421..4bd42abb9e8 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.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 --- -# Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE)** +# Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE ALL)** The GitLab Managed Apps were deprecated in GitLab 14.0 in favor of user-controlled Cluster Management projects. @@ -39,16 +39,16 @@ See also [video walk-throughs](#video-walk-throughs) with examples. Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they. -1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on +1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm documentation on [how to migrate from Helm v2 to Helm v3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/), and clean up the Helm v2 releases after you are confident that they have been successfully migrated. 1. In this step you should already have only Helm v3 releases. Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) the paths for the applications that you would like to manage with this project. Although you could uncomment all the ones you want to - managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during + managed at once, you should repeat the following steps separately for each app, so you do not get lost during the process. -1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed +1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version deployed for your app. Take a GitLab Runner Helm v3 release as an example: The following command lists the releases and their versions: @@ -62,11 +62,11 @@ See also [video walk-throughs](#video-walk-throughs) with examples. Take the version from the `CHART` column which is in the format `{release}-v{chart_version}`, then edit the `version:` attribute in the `./applications/gitlab-runner/helmfile.yaml`, so that it matches the version - you have currently deployed. This is a safe step to avoid upgrading versions during this migration. + you have deployed. This is a safe step to avoid upgrading versions during this migration. Make sure you replace `gitlab-managed-apps` from the above command if you have your apps deployed to a different namespace. -1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently +1. Edit the `applications/{app}/values.yaml` associated with your app to match the deployed values. For example, for GitLab Runner: 1. Copy the output of the following command (it might be big): @@ -77,7 +77,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples. 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. - This safe step guarantees that no unexpected default values overwrite your currently deployed values. + This safe step guarantees that no unexpected default values overwrite your deployed values. For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. 1. Some apps require special attention: diff --git a/doc/user/compliance/compliance_center/index.md b/doc/user/compliance/compliance_center/index.md new file mode 100644 index 00000000000..bd3409abe01 --- /dev/null +++ b/doc/user/compliance/compliance_center/index.md @@ -0,0 +1,354 @@ +--- +type: reference, howto +stage: Govern +group: Compliance +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 +--- + +# Compliance center **(ULTIMATE ALL)** + +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122931) from Compliance report in GitLab 16.3. + +See report and manage standards adherence, violations, and compliance frameworks for the group + +## Standards adherence dashboard + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125875) GraphQL APIs in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `compliance_adherence_report`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125444) standards adherence dashboard in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `adherence_report_ui`. 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 flags](../../../administration/feature_flags.md) named +`compliance_adherence_report` and `adherence_report_ui`. On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Standards adherence dashboard lists the adherence status of projects complying to GitLab standard. + +### View the standards adherence dashboard + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +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 **Secure > Compliance center**. + +### GitLab standard + +GitLab standard consists of three rules: + +- Prevent authors as approvers. +- Prevent committers as approvers. +- At least two approvals. + +#### Prevent authors as approvers + +To comply with GitLab standard, you must prevent users from approving their own merge requests. For more information, +see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). + +On self-managed GitLab, when instance-level setting for [prevent approval by author](../../../administration/merge_requests_approvals.md) +is updated, the adherence status for all the projects on the instance is not updated automatically. +To update the adherence status for these projects, the group-level or the project-level setting must be updated. + +#### Prevent committers as approvers + +To comply with GitLab standard, you must prevent users from approving merge requests where they've added commits. For +more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). + +On self-managed GitLab, when instance-level setting for [prevent approvals by users who add commits](../../../administration/merge_requests_approvals.md) +is updated, the adherence status for all the projects on the instance is not updated automatically. +To update the adherence status for these projects, the group-level or the project-level setting must be updated. + +#### At least two approvals + +To comply with GitLab standard, you must have at least two users approve a merge request to get it merged. For more +information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). + +## Compliance violations report + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. +> - Compliance violation drawer [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. +> - [Replaced](https://gitlab.com/groups/gitlab-org/-/epics/5237) by merge request violations in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `compliance_violations_report`. Disabled by default. +> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. +> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/5237) in GitLab 14.10. [Feature flag `compliance_violations_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/346266) removed. +> - [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. + +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), + 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]`. +- A list of users that committed changes to the merge request. +- A list of users that commented on the merge request. +- A list of users that approved the merge request. +- The user that merged the merge request. + +### View the compliance violations report for a group + +> Target branch search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358414) in GitLab 16.0. + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +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 **Secure > Compliance center**. + +You can sort the compliance report on: + +- Severity level. +- Type of violation. +- Merge request title. + +You can filter the compliance violations report on: + +- Project. +- Date range of merge. +- Target branch. + +Select a row to see details of the compliance violation. + +#### Severity levels + +Each compliance violation has one of the following severities. + +<!-- vale gitlab.SubstitutionWarning = NO --> + +| Icon | Severity level | +|:----------------------------------------------|:---------------| +| **{severity-critical, 18, gl-fill-red-800}** | Critical | +| **{severity-high, 18, gl-fill-red-600}** | High | +| **{severity-medium, 18, gl-fill-orange-400}** | Medium | +| **{severity-low, 18, gl-fill-orange-300}** | Low | +| **{severity-info, 18, gl-fill-blue-400}** | Info | + +<!-- vale gitlab.SubstitutionWarning = YES --> + +#### Violation types + +From [GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870), these are the available compliance violations. + +| Violation | Severity level | Category | Description | +|:----------------------------------|:---------------|:----------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Author approved merge request | High | [Separation of duties](#separation-of-duties) | Author of the merge request approved their own merge request. For more information, see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | +| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | Committers of the merge request approved the merge request they contributed to. For more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | +| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | Merge request was merged with fewer than two approvals. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). | + +The following are unavailable compliance violations that are tracked in [epic 5237](https://gitlab.com/groups/gitlab-org/-/epics/5237). + +<!-- vale gitlab.SubstitutionWarning = NO --> + +| Violation | Severity level | Category | Description | +|:-------------------------------------|:---------------|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------| +| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | Merge requests pipeline failed and was merged. | +| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | Merge request pipeline passed with warnings and was merged. | +| Code coverage down more than 10% | High | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | +| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | +| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | +| Code coverage down less than 1% | Info | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | + +<!-- vale gitlab.SubstitutionWarning = YES --> + +##### Separation of duties + +GitLab supports a separation of duties policy between users who create and approve merge requests. Our criteria for the +separation of duties is: + +- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). +- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). +- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md). + +### Chain of Custody report + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. +> - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed. +> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112092) in GitLab 15.9. Feature flag `all_commits_compliance_report` removed. + +The Chain of Custody report provides a 1 month trailing window of all commits to a project under the group. + +To generate the report for all commits, GitLab: + +1. Fetches all projects under the group. +1. For each project, fetches the last 1 month of commits. Each project is capped at 1024 commits. If there are more than + 1024 commits in the 1-month window, they are truncated. +1. Writes the commits to a CSV file. The file is truncated at 15 MB because the report is emailed as an attachment + (GitLab 15.5 and later). + +The report includes: + +- Commit SHA. +- Commit author. +- Committer. +- Date committed. +- Group. +- Project. + +If the commit has a related merge commit, then the following are also included: + +- Merge commit SHA. +- Merge request ID. +- User who merged the merge request. +- Merge date. +- Pipeline ID. +- Merge request approvers. + +#### Generate Chain of Custody report + +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 **Secure > Compliance center**. +1. Select **List of all merge commits**. + +Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. + +#### Generate commit-specific Chain of Custody report + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6. +> - Support for including all commits instead of only merge commits [added](https://gitlab.com/gitlab-org/gitlab/-/issues/393446) in GitLab 15.10. + +You can generate a commit-specific Chain of Custody report for a given commit SHA. This report provides only the +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 **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}**). +1. Enter the commit SHA, and then select **Export commit custody report**. + +Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. + +Alternatively, use a direct link: `https://gitlab.com/groups/<group-name>/-/security/merge_commit_reports.csv?commit_sha={optional_commit_sha}`, +passing in an optional value to the `commit_sha` query parameter. + +## Compliance frameworks report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10. + +With compliance frameworks report, you can see the compliance frameworks that are applied to projects in a group. Each row of the report shows: + +- Project name. +- Project path. +- Compliance framework label if the project has one assigned. + +The default framework for the group has a **default** badge. + +### View the compliance frameworks report for a group + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +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 **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. + +### Apply a compliance framework to projects in a group + +> - Adding compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. +> - Adding compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. + +You can apply a compliance framework to projects in a group. + +Prerequisites: + +- You must have the Owner role for the group. + +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 **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**. +1. Select an existing compliance framework or create a new one. + +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 **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 **Apply framework to selected projects**. +1. Select framework to apply. +1. Select **Apply**. + +### Remove a compliance framework from projects in a group + +> - Removing compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. +> - Removing compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. + +You can remove a compliance framework from projects in a group. + +Prerequisites: + +- You must have the Owner role for the group. + +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 **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 **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 compliance frameworks on projects in a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0. + +Export a report of compliance frameworks that are applied to projects in a group. Reports: + +- Do not use filters on the framework report. +- Are truncated at 15 MB so the email attachment too large. + +Prerequisites: + +- You must be an administrator or have the Owner role for the group. + +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 **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 + +A report is compiled and delivered to your email inbox as an attachment. + +#### Filter the compliance frameworks report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11. + +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 **Secure > Compliance center**. +1. On the page, select the **Frameworks** tab. +1. In the search field: + 1. Select the attribute you want to filter by. + 1. Select an operator. + 1. Select from the list of options or enter text for the search. +1. Select **Search** (**{search}**). + +Repeat this process to filter by multiple attributes. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index ab80fbbba8e..998e9c81d18 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -1,297 +1,11 @@ --- -type: reference, howto -stage: Govern -group: Compliance -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: '../compliance_center/index.md' +remove_date: '2023-09-20' --- -# Compliance reports **(ULTIMATE)** +This document was moved to [another location](../compliance_center/index.md). -See reports about compliance violations and compliance frameworks for the group. - -## Compliance violations report - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in GitLab 12.8 as Compliance Dashboard. -> - Compliance violation drawer [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299357) in GitLab 14.1. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/299360) to compliance report in GitLab 14.2. -> - [Replaced](https://gitlab.com/groups/gitlab-org/-/epics/5237) by merge request violations in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `compliance_violations_report`. Disabled by default. -> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. -> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/5237) in GitLab 14.10. [Feature flag `compliance_violations_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/346266) removed. -> - [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. - -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), - 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]`. -- A list of users that committed changes to the merge request. -- A list of users that commented on the merge request. -- A list of users that approved the merge request. -- The user that merged the merge request. - -### View the compliance violations report for a group - -> Target branch search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358414) in GitLab 16.0. - -Prerequisites: - -- You must be an administrator or have the Owner role for the group. - -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 **Secure > Compliance report**. - -You can sort the compliance report on: - -- Severity level. -- Type of violation. -- Merge request title. - -You can filter the compliance violations report on: - -- Project. -- Date range of merge. -- Target branch. - -Select a row to see details of the compliance violation. - -#### Severity levels - -Each compliance violation has one of the following severities. - -<!-- vale gitlab.SubstitutionWarning = NO --> - -| Icon | Severity level | -|:----------------------------------------------|:---------------| -| **{severity-critical, 18, gl-fill-red-800}** | Critical | -| **{severity-high, 18, gl-fill-red-600}** | High | -| **{severity-medium, 18, gl-fill-orange-400}** | Medium | -| **{severity-low, 18, gl-fill-orange-300}** | Low | -| **{severity-info, 18, gl-fill-blue-400}** | Info | - -<!-- vale gitlab.SubstitutionWarning = YES --> - -#### Violation types - -From [GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870), these are the available compliance violations. - -| Violation | Severity level | Category | Description | -|:----------------------------------|:---------------|:----------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Author approved merge request | High | [Separation of duties](#separation-of-duties) | Author of the merge request approved their own merge request. For more information, see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | -| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | Committers of the merge request approved the merge request they contributed to. For more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | -| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | Merge request was merged with fewer than two approvals. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). | - -The following are unavailable compliance violations that are tracked in [epic 5237](https://gitlab.com/groups/gitlab-org/-/epics/5237). - -<!-- vale gitlab.SubstitutionWarning = NO --> - -| Violation | Severity level | Category | Description | -|:-------------------------------------|:---------------|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------| -| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | Merge requests pipeline failed and was merged. | -| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | Merge request pipeline passed with warnings and was merged. | -| Code coverage down more than 10% | High | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | -| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | -| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | -| Code coverage down less than 1% | Info | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | - -<!-- vale gitlab.SubstitutionWarning = YES --> - -##### Separation of duties - -GitLab supports a separation of duties policy between users who create and approve merge requests. Our criteria for the -separation of duties is: - -- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). -- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). -- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md). - -### Chain of Custody report - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. -> - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed. -> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112092) in GitLab 15.9. Feature flag `all_commits_compliance_report` removed. - -The Chain of Custody report provides a 1 month trailing window of all commits to a project under the group. - -To generate the report for all commits, GitLab: - -1. Fetches all projects under the group. -1. For each project, fetches the last 1 month of commits. Each project is capped at 1024 commits. If there are more than - 1024 commits in the 1-month window, they are truncated. -1. Writes the commits to a CSV file. The file is truncated at 15 MB because the report is emailed as an attachment - (GitLab 15.5 and later). - -The report includes: - -- Commit SHA. -- Commit author. -- Committer. -- Date committed. -- Group. -- Project. - -If the commit has a related merge commit, then the following are also included: - -- Merge commit SHA. -- Merge request ID. -- User who merged the merge request. -- Merge date. -- Pipeline ID. -- Merge request approvers. - -#### Generate Chain of Custody report - -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 **Secure > Compliance report**. -1. Select **List of all merge commits**. - -Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. - -#### Generate commit-specific Chain of Custody report - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in GitLab 13.6. -> - Support for including all commits instead of only merge commits [added](https://gitlab.com/gitlab-org/gitlab/-/issues/393446) in GitLab 15.10. - -You can generate a commit-specific Chain of Custody report for a given commit SHA. This report provides only the -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 **Secure > Compliance report**. -1. At the top of the compliance report, to the right of **List of all commits**, select the down arrow - (**{chevron-lg-down}**). -1. Enter the commit SHA, and then select **Export commit custody report**. - -Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. - -Alternatively, use a direct link: `https://gitlab.com/groups/<group-name>/-/security/merge_commit_reports.csv?commit_sha={optional_commit_sha}`, -passing in an optional value to the `commit_sha` query parameter. - -## Compliance frameworks report - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387910) in GitLab 15.10. - -With compliance frameworks report, you can see the compliance frameworks that are applied to projects in a group. Each row of the report shows: - -- Project name. -- Project path. -- Compliance framework label if the project has one assigned. - -The default framework for the group has a **default** badge. - -### View the compliance frameworks report for a group - -Prerequisites: - -- You must be an administrator or have the Owner role for the group. - -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 **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. - -### Apply a compliance framework to projects in a group - -> - Adding compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. -> - Adding compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. - -You can apply a compliance framework to projects in a group. - -Prerequisites: - -- You must have the Owner role for the group. - -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 **Secure > Compliance report**. -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**. -1. Select an existing compliance framework or create a new one. - -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 **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. Select multiple projects. -1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. -1. Select framework to apply. -1. Select **Apply**. - -### Remove a compliance framework from projects in a group - -> - Removing compliance frameworks using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383209) in GitLab 15.11. -> - Removing compliance frameworks without using bulk actions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394795) in GitLab 16.0. - -You can remove a compliance framework from projects in a group. - -Prerequisites: - -- You must have the Owner role for the group. - -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 **Secure > Compliance report**. -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 **Secure > Compliance report**. -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 compliance frameworks on projects in a group - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387912) in GitLab 16.0. - -Export a report of compliance frameworks that are applied to projects in a group. Reports: - -- Do not use filters on the framework report. -- Are truncated at 15 MB so the email attachment too large. - -Prerequisites: - -- You must be an administrator or have the Owner role for the group. - -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 **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. On the Frameworks tab, select the **Export as CSV** action in the top right corner - -A report is compiled and delivered to your email inbox as an attachment. - -#### Filter the compliance frameworks report - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387911) in GitLab 15.11. - -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 **Secure > Compliance report**. -1. On the page, select the **Frameworks** tab. -1. In the search field: - 1. Select the attribute you want to filter by. - 1. Select an operator. - 1. Select from the list of options or enter text for the search. -1. Select **Search** (**{search}**). - -Repeat this process to filter by multiple attributes. +<!-- This redirect file can be deleted after <2023-09-20>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (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/compliance/index.md b/doc/user/compliance/index.md index ad36684d987..51053c03d8c 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -5,11 +5,11 @@ group: Compliance 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 --- -# Compliance **(ULTIMATE)** +# Compliance **(ULTIMATE ALL)** The compliance tools provided by GitLab help you keep an eye on various aspects of your project, including: -- [Compliance report](compliance_report/index.md). +- [Compliance center](compliance_center/index.md). - [License approval policies](license_approval_policies.md). - [License list](license_list.md). - [License scanning of CycloneDX files](license_scanning_of_cyclonedx_files/index.md). diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index 96a4a08249a..e3350b1ae10 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -5,7 +5,7 @@ group: Security Policies 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 --- -# License approval policies **(ULTIMATE)** +# License approval policies **(ULTIMATE ALL)** > - [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. diff --git a/doc/user/compliance/license_check_rules.md b/doc/user/compliance/license_check_rules.md deleted file mode 100644 index 3007d04a8c1..00000000000 --- a/doc/user/compliance/license_check_rules.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -redirect_to: 'license_approval_policies.md' -remove_date: '2023-07-25' ---- - -# License Check Policies (removed) **(ULTIMATE)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/397067) in 16.0. -Use [License Approval Policies](license_approval_policies.md) instead. - -<!-- This redirect file can be deleted after <2023-07-25>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 238cf10cba9..00578219016 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -3,845 +3,12 @@ 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 (deprecated) **(ULTIMATE)** +# License Compliance (removed) **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. You should instead migrate to use [License approval policies](../license_approval_policies.md) and the [new method of license scanning](../license_scanning_of_cyclonedx_files/index.md) prior to GitLab 16.1. - -If you're using [GitLab CI/CD](../../../ci/index.md), you can use License Compliance to search your -project's dependencies for their licenses. You can then decide whether to allow or deny the use of -each license. For example, if your application uses an external (open source) library whose license -is incompatible with yours, then you can deny the use of that license. - -To detect the licenses in use, License Compliance uses the [License Finder](https://github.com/pivotal/LicenseFinder) scan tool that runs as part of the CI/CD pipeline. The License Compliance job is not dependent on any other job in -a pipeline. - -For the job to activate, License Finder needs to find a compatible package definition in the project directory. For details, see the [Activation on License Finder documentation](https://github.com/pivotal/LicenseFinder#activation). -GitLab checks the License Compliance report, compares the -licenses between the source and target branches, and shows the information right on the merge -request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that -need a decision from you. In addition, you can [manually allow or deny](../license_approval_policies.md) licenses in your -project's security policies section. If a denied license is detected in a new commit, -GitLab blocks any merge requests containing that commit and instructs the developer to remove the -license. - -NOTE: -Starting with GitLab 15.9, License Compliance can detect the licenses in use -[using Dependency Scanning CI jobs](../license_scanning_of_cyclonedx_files/index.md) -instead of the License Scanning ones. - -NOTE: -If the license compliance report doesn't have anything to compare to, no information -is displayed in the merge request area. That is the case when you add the -`license_scanning` job in your `.gitlab-ci.yml` for the first time. -Consecutive merge requests have something to compare to and the license -compliance report is shown properly. - -The results are saved as a -[License Compliance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) -that you can later download and analyze. - -WARNING: -License Compliance Scanning does not support run-time installation of compilers and interpreters. - -## Enable License Compliance - -To enable License Compliance in your project's pipeline, either: - -- Enable [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) - (provided by [Auto DevOps](../../../topics/autodevops/index.md)). -- Include the [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) in your `.gitlab-ci.yml` file. - -License Compliance is not supported when GitLab is run with FIPS mode enabled. - -### Include the License Scanning template - -Prerequisites: - -- [GitLab Runner](../../../ci/runners/index.md) available, with the - [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). If you're using the - shared runners on GitLab.com, this is enabled by default. -- License Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the - `.gitlab-ci.yml` file, the `test` stage is required. -- [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) must be disabled. - -To [include](../../../ci/yaml/index.md#includetemplate) the -[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml), add it to your `.gitlab-ci.yml` file: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml -``` - -The included template creates a `license_scanning` job in your CI/CD pipeline and scans your -dependencies to find their licenses. - -## License expressions - -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). -License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, -if a dependency has two licenses, and one of them is allowed and the other is denied by the project [license approval policy](../license_approval_policies.md), -GitLab evaluates the composite license as _denied_, as this is the safer option. -The ability to support other license expression operators (like `OR`, `WITH`) is tracked -in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). - -## Supported languages and package managers - -The following languages and package managers are supported. - -Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. - -| Language | Package managers | Notes | -|------------|----------------------------------------------------------------------------------------------|-------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) (7 and earlier) | | -| Go | [Godep](https://github.com/tools/godep) ([deprecated](../../../update/deprecations.md#godep-support-in-license-compliance)), [go mod](https://github.com/golang/go/wiki/Modules) | | -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | -| .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | -| Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | -| Ruby | [gem](https://rubygems.org/) | | - -### Experimental support - -The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types). -The reported licenses might be incomplete or inaccurate. - -| Language | Package managers | -|------------|---------------------------------------------------------------------------------------------------------------| -| JavaScript | [Yarn](https://yarnpkg.com/) | -| Go | `go get`, `gvt`, `glide`, `dep`, `trash`, `govendor` | -| Erlang | [Rebar](https://rebar3.org/) | -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage), [CocoaPods](https://cocoapods.org/) v0.39 and below | -| Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | -| C++/C | [Conan](https://conan.io/) | -| Rust | [Cargo](https://crates.io/) | -| PHP | [Composer](https://getcomposer.org/) | - -## Available CI/CD variables - -License Compliance can be configured using CI/CD variables. - -| CI/CD variable | Required | Description | -|-----------------------------|----------|-------------| -| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects). | -| `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | -| `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | -| `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. [Configuration](#selecting-the-version-of-python) | -| `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | -| `GRADLE_CLI_OPTS` | no | Additional arguments for the Gradle executable. If not supplied, defaults to `--exclude-task=test`. | -| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci.yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | -| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. [Configuration](#selecting-the-version-of-java) | -| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. [Configuration](#selecting-the-version-of-python) | -| `MAVEN_CLI_OPTS` | no | Additional arguments for the `mvn` executable. If not supplied, defaults to `-DskipTests`. | -| `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | -| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | -| `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | - -## Installing custom dependencies - -> Introduced in GitLab 11.4. - -The `license_finder` image already embeds many auto-detection scripts, languages, -and packages. Nevertheless, it's almost impossible to cover all cases for all projects. -That's why sometimes it's necessary to install extra packages, or to have extra steps -in the project automated setup, like the download and installation of a certificate. -For that, a `SETUP_CMD` CI/CD variable can be passed to the container, -with the required commands to run before the license detection. - -If present, this variable overrides the setup step necessary to install all the packages -of your application (for example: for a project with a `Gemfile`, the setup step could be -`bundle install`). - -For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -variables: - SETUP_CMD: sh my-custom-install-script.sh -``` - -In this example, `my-custom-install-script.sh` is a shell script at the root -directory of your project. - -## Working with Monorepos - -Depending on your language, you may need to specify the path to the individual -projects of a monorepo using the `LICENSE_FINDER_CLI_OPTS` variable. Passing in -the project paths can significantly speed up builds over using the `--recursive` -License Finder option. - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -variables: - LICENSE_FINDER_CLI_OPTS: "--aggregate_paths=relative-path/to/sub-project/one relative-path/to/sub-project/two" -``` - -## Overriding the template - -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. - -If you want to override the job definition (for example, change properties like -`variables` or `dependencies`), you need to declare a `license_scanning` job -after the template inclusion and specify any additional keys under it. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - CI_DEBUG_TRACE: "true" -``` - -## Configuring Maven projects - -The License Compliance tool provides a `MAVEN_CLI_OPTS` CI/CD variable which can hold -the command line arguments to pass to the `mvn install` command which is executed under the hood. -Feel free to use it for the customization of Maven execution. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - MAVEN_CLI_OPTS: --debug -``` - -`mvn install` runs through all of the [build life cycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) -stages prior to `install`, including `test`. Running unit tests is not directly -necessary for the license scanning purposes and consumes time, so it's skipped -by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want -to supply custom `MAVEN_CLI_OPTS` and skip tests at the same time, don't forget -to explicitly add `-DskipTests` to your options. -If you still need to run tests during `mvn install`, add `-DskipTests=false` to -`MAVEN_CLI_OPTS`. - -### Using private Maven repositories - -If you have a private Maven repository which requires login credentials, -you can use the `MAVEN_CLI_OPTS` CI/CD variable. - -Read more on [how to use private Maven repositories](../../application_security/index.md#using-private-maven-repositories). - -You can also use `MAVEN_CLI_OPTS` to connect to a trusted Maven repository that uses a self-signed -or internally trusted certificate. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - MAVEN_CLI_OPTS: -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.ignore.validity.dates=true -Dmaven.wagon.http.ssl.insecure=true -``` - -Alternatively, you can use a Java key store to verify the TLS connection. For instructions on how to -generate a key store file, see the -[Maven Guide to Remote repository access through authenticated HTTPS](https://maven.apache.org/guides/mini/guide-repository-ssl.html). - -## Selecting the version of Java - -License Compliance uses Java 8 by default. You can specify a different Java version using `LM_JAVA_VERSION`. - -`LM_JAVA_VERSION` only accepts versions: 8, 11, 14, 15. - -## Selecting the version of Python - -> - [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/36) in GitLab 12.0. -> - In [GitLab 12.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12032), Python 3.5 became the default. -> - In [GitLab 12.7](https://gitlab.com/gitlab-org/security-products/license-management/-/merge_requests/101), Python 3.8 became the default. - -License Compliance uses Python 3.8 and pip 19.1 by default. -If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 -by setting the `LM_PYTHON_VERSION` CI/CD variable to `2`. - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - LM_PYTHON_VERSION: 2 -``` - -`LM_PYTHON_VERSION` or `ASDF_PYTHON_VERSION` can be used to specify the desired version of Python. When both variables are specified `LM_PYTHON_VERSION` takes precedence. - -## Custom root certificates for Python - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -### Using private Python repositories - -If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-cicd-variables) -to specify its location. - -## Configuring npm projects - -You can configure npm projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) -file. - -### Using private npm registries - -If you have a private npm registry you can use the -[`registry`](https://docs.npmjs.com/using-npm/config/#registry) -setting to specify its location. - -For example: - -```plaintext -registry = https://npm.example.com -``` - -### Custom root certificates for npm - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) -setting. - -For example: - -```plaintext -strict-ssl = false -``` - -## Configuring Yarn projects - -You can configure Yarn projects by using a [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc/) -file. - -### Using private Yarn registries - -If you have a private Yarn registry you can use the -[`npmRegistryServer`](https://yarnpkg.com/configuration/yarnrc/#npmRegistryServer) -setting to specify its location. - -For example: - -```plaintext -npmRegistryServer: "https://npm.example.com" -``` - -### Custom root certificates for Yarn - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -## Configuring Bower projects - -You can configure Bower projects by using a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) -file. - -### Using private Bower registries - -If you have a private Bower registry you can use the -[`registry`](https://bower.io/docs/config/#bowerrc-specification) -setting to specify its location. - -For example: - -```plaintext -{ - "registry": "https://registry.bower.io" -} -``` - -### Custom root certificates for Bower - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by -specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) -file. - -## Configuring Bundler projects - -### Using private Bundler registries - -If you have a private Bundler registry you can use the -[`source`](https://bundler.io/man/gemfile.5.html#GLOBAL-SOURCES) -setting to specify its location. - -For example: - -```plaintext -source "https://gems.example.com" -``` - -### Custom root certificates for Bundler - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by -specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) -[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) -in the job definition. - -## Configuring Cargo projects - -### Using private Cargo registries - -If you have a private Cargo registry you can use the -[`registries`](https://doc.rust-lang.org/cargo/reference/registries.html) -setting to specify its location. - -For example: - -```toml -[registries] -my-registry = { index = "https://my-intranet:8080/git/index" } -``` - -### Custom root certificates for Cargo - -To supply a custom root certificate to complete TLS verification, do one of the following: - -- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). -- Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) - [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) - in the job definition. - -## Configuring Composer projects - -### Using private Composer registries - -If you have a private Composer registry you can use the -[`repositories`](https://getcomposer.org/doc/05-repositories.md) -setting to specify its location. - -For example: - -```json -{ - "repositories": [ - { "packagist.org": false }, - { - "type": "composer", - "url": "https://composer.example.com" - } - ], - "require": { - "monolog/monolog": "1.0.*" - } -} -``` - -### Custom root certificates for Composer - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by -specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) -[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) -in the job definition. - -## Configuring Conan projects - -You can configure [Conan](https://conan.io/) projects by adding a `.conan` directory to your -project root. The project root serves as the [`CONAN_USER_HOME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-user-home). - -Consult the [Conan](https://docs.conan.io/en/latest/reference/config_files/conan.conf.html#conan-conf) -documentation for a list of settings that you can apply. - -The `license_scanning` job runs in a [Debian 10](https://www.debian.org/releases/buster/) Docker -image. The supplied image ships with some build tools such as [CMake](https://cmake.org/) and [GCC](https://gcc.gnu.org/). -However, not all project types are supported by default. To install additional tools needed to -compile dependencies, use a [`before_script`](../../../ci/yaml/index.md#before_script) -to install the necessary build tools using the [`apt`](https://wiki.debian.org/PackageManagementTools) -package manager. For a comprehensive list, consult [the Conan documentation](https://docs.conan.io/en/latest/introduction.html#all-platforms-all-build-systems-and-compilers). - -The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) -to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name) -to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) -for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/index.md#fetch-conan-package-information-from-the-package-registry) -if a GitLab remote is specified in the `.conan/remotes.json` file. - -To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) -matching the name of the remote specified in the `.conan/remotes.json` file. - -NOTE: -[MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild) projects aren't supported. The -`license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). -Additional setup may be required to build packages for this project configuration. - -### Using private Conan registries - -By default, [Conan](https://conan.io/) uses the `conan-center` remote. For example: - -```json -{ - "remotes": [ - { - "name": "conan-center", - "url": "https://conan.bintray.com", - "verify_ssl": true - } - ] -} -``` - -To fetch dependencies from an alternate remote, specify that remote in a `.conan/remotes.json`. For -example: - -```json -{ - "remotes": [ - { - "name": "gitlab", - "url": "https://gitlab.com/api/v4/packages/conan", - "verify_ssl": true - } - ] -} -``` - -If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protect-a-cicd-variable) -following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). - -### Custom root certificates for Conan - -You can provide custom certificates by adding a `.conan/cacert.pem` file to the project root and -setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) -to `.conan/cacert.pem`. - -If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), this -variable's X.509 certificates are installed in the Docker image's default trust store and Conan is -configured to use this as the default `CA_CERT_PATH`. - -## Configuring Go projects - -To configure [Go modules](https://github.com/golang/go/wiki/Modules) -based projects, specify [CI/CD variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -in the `license_scanning` job's [variables](#available-cicd-variables) section in `.gitlab-ci.yml`. - -If a project has [vendored](https://pkg.go.dev/cmd/go#hdr-Vendor_Directories) its modules, -then the combination of the `vendor` directory and `mod.sum` file are used to detect the software -licenses associated with the Go module dependencies. - -### Using private Go registries - -You can use the [`GOPRIVATE`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -and [`GOPROXY`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -environment variables to control where modules are sourced from. Alternatively, you can use -[`go mod vendor`](https://go.dev/ref/mod#tmp_28) to vendor a project's modules. - -### Custom root certificates for Go - -You can specify the [`-insecure`](https://pkg.go.dev/cmd/go/internal/get) flag by exporting the -[`GOFLAGS`](https://pkg.go.dev/cmd/go#hdr-Environment_variables) -environment variable. For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - GOFLAGS: '-insecure' -``` - -### Using private NuGet registries - -If you have a private NuGet registry you can add it as a source -by adding it to the [`packageSources`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) -section of a [`nuget.config`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file) file. - -For example: - -```xml -<?xml version="1.0" encoding="utf-8"?> -<configuration> - <packageSources> - <clear /> - <add key="custom" value="https://nuget.example.com/v3/index.json" /> - </packageSources> -</configuration> -``` - -### Custom root certificates for NuGet - -You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - -### Migration from `license_management` to `license_scanning` - -WARNING: -The `license_management` job was deprecated in GitLab 12.8. The `License-Management.gitlab-ci.yml` template was removed from GitLab 14.0. - -In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. -GitLab 13.0 drops support for `license_management`. -If you're using a custom setup for License Compliance, you're required -to update your CI configuration accordingly: - -1. Change the CI template to `License-Scanning.gitlab-ci.yml`. -1. Change the job name to `license_scanning` (if you mention it in `.gitlab-ci.yml`). -1. Change the artifact name to `license_scanning`, and the filename to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). - -For example, the following `.gitlab-ci.yml`: - -```yaml -include: - - template: License-Management.gitlab-ci.yml - -license_management: - artifacts: - reports: - license_management: gl-license-management-report.json -``` - -Should be changed to: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - artifacts: - reports: - license_scanning: gl-license-scanning-report.json -``` - -If you use the `license_management` artifact in GitLab 13.0 or later, the License Compliance job generates this error: - -```plaintext -WARNING: Uploading artifacts to coordinator... failed id=:id responseStatus=400 Bad Request status=400 Bad Request token=:sha - -FATAL: invalid_argument -``` - -If you encounter this error, follow the instructions described in this section. - -## Running License Compliance in an offline environment - -For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the License Compliance job to -successfully run. For more information, see [Offline environments](../../application_security/offline_deployments/index.md). - -### Requirements for offline License Compliance - -To use License Compliance in an offline environment, you need: - -- To meet the standard [License Compliance prerequisites](#include-the-license-scanning-template). -- Docker Container Registry with locally available copies of License Compliance [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - -NOTE: -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) -in an offline environment if you prefer using only locally available Docker images. However, we -recommend keeping the pull policy setting to `always` if not in an offline environment, as this -enables the use of updated scanners in your CI/CD pipelines. - -### Make GitLab License Compliance analyzer images available inside your Docker registry - -For License Compliance with all [supported languages and package managers](#supported-languages-and-package-managers), -import the following default License Compliance analyzer images from `registry.gitlab.com` to your -offline [local Docker container registry](../../packages/container_registry/index.md): - -```plaintext -registry.gitlab.com/security-products/license-finder:latest -``` - -The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. These scanners are [updated periodically](../../application_security/index.md#vulnerability-scanner-maintenance) -with new definitions, so consider if you are able to make periodic updates yourself. - -For details on saving and transporting Docker images as a file, see the Docker documentation on -[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), -[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). - -### Set License Compliance CI/CD variables to use local License Compliance analyzers - -Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to -the License Compliance Docker image hosted on your local Docker container registry: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - image: - name: localhost:5000/analyzers/license-management:latest -``` - -The License Compliance job should now use local copies of the License Compliance analyzers to scan -your code and generate security reports, without requiring internet access. - -Additional configuration may be needed for connecting to private registries for: - -- [Bower](#using-private-bower-registries), -- [Bundler](#using-private-bundler-registries), -- [Conan](#using-private-bower-registries), -- [Go](#using-private-go-registries), -- [Maven repositories](#using-private-maven-repositories), -- [npm](#using-private-npm-registries), -- [Python repositories](#using-private-python-repositories), -- [Yarn](#using-private-yarn-registries). - -### SPDX license list name matching - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in GitLab 13.3. - -Prior to GitLab 13.3, offline environments required an exact name match for [project policies](../license_approval_policies.md). -In GitLab 13.3 and later, GitLab matches the name of [project policies](../license_approval_policies.md) -with license names from the [SPDX license list](https://spdx.org/licenses/). -A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab -instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). - -## 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. - -## Troubleshooting - -### `ASDF_PYTHON_VERSION` does not automatically install the version - -Defining a non-latest Python version in `ASDF_PYTHON_VERSION` [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: - -1. Define the required version by setting the `ASDF_PYTHON_VERSION` CI/CD variable. -1. Pass a custom script to the `SETUP_CMD` CI/CD variable to install the required version and dependencies. - -For example: - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - SETUP_CMD: ./setup.sh - ASDF_PYTHON_VERSION: "3.7.2" - before_script: - - echo "asdf install python 3.7.2 && pip install -r requirements.txt" > setup.sh - - chmod +x setup.sh - - apt-get -y update - - apt-get -y install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl git -``` - -### `ERROR -- : asdf: No preset version installed for command` - -This error occurs when the version of the tools used by your project -do not match the version of the pre-installed tools available in the -`license_scanning` Docker image. The `license_scanning` job uses -[asdf-vm](https://asdf-vm.com/) to activate the appropriate version of -a tool that your project relies on. For example, if your project relies on a specific -version of [Node.js](https://nodejs.org/) or any other supported tool you can -specify the desired version by adding a -[`.tool-versions`](https://asdf-vm.com/#/core-configuration?id=tool-versions) file to the project -or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to -activate the appropriate version. - -For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) -and version `2.7.4` of [Ruby](https://www.ruby-lang.org/). - -```plaintext -nodejs 12.16.3 -ruby 2.7.4 -``` - -The next example shows how to activate the same versions of the tools mentioned above by using CI/CD variables defined in your -project's `.gitlab-ci.yml` file. - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - ASDF_NODEJS_VERSION: '12.16.3' - ASDF_RUBY_VERSION: '2.7.4' -``` - -A full list of variables can be found in [CI/CD variables](#available-cicd-variables). - -To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: - -```shell -$ docker run --entrypoint='' -ti --rm registry.gitlab.com/security-products/license-finder:4 \ - /bin/bash -c 'dpkg -i /opt/toolcache/*.deb && asdf list' -... -dotnet-core - 3.1.302 -elixir - 1.10.4 -golang - 1.15.5 - 1.16.2 -gradle -No versions installed -java - 11 - 14 - 15 - 8 -maven -No versions installed -nodejs - 10.21.0 - 12.18.2 - 14.17.1 -php - 7.4.8 -python - 2.7.18 - 3.3.7 - 3.4.10 - 3.5.9 - 3.6.11 - 3.7.7 - 3.8.5 -ruby - 2.4.10 - 2.4.5 - 2.4.9 - 2.5.8 - 2.6.0 - 2.6.1 - 2.6.2 - 2.6.3 - 2.6.4 - 2.6.5 - 2.6.6 - 2.7.0 - 2.7.1 - 2.7.2 -rust - 1.45.0 -``` - -It might take more than 10 minutes to run the command above. -This is because it installs every single tool version available in the Docker image. - -To interact with the `license_scanning` runtime environment use the following command: - -```shell -$ docker run -it --entrypoint='' registry.gitlab.com/security-products/license-finder:4 /bin/bash -l -root@6abb70e9f193:~# -``` - -NOTE: -Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet) is currently not supported. - -### LicenseFinder::Maven: is not installed error - -If your project contains a `mvnw` or `mvnw.cmd` file, then the license scanning job may fail with the `LicenseFinder::Maven: is not installed error` error. To resolve this, modify the license scanning job to remove the files in the `before_script` section. Example: - -```yaml -include: - - template: License-Scanning.gitlab-ci.yml - -license_scanning: - before_script: - - rm mvnw - - rm mvnw.cmd -``` +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 deec4e28911..96ea43e5ce2 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -5,7 +5,7 @@ group: Threat Insights 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 --- -# License list **(ULTIMATE)** +# License list **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. @@ -16,13 +16,13 @@ For the licenses to appear under the license list, the following requirements must be met: 1. You must be generating an SBOM file with components from one of our [one of our supported languages](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). -1. If using our [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) to generate the SBOM file, then your project must use at least one of the [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). +1. If using our [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) to generate the SBOM file, then 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). 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 License Compliance CI/CD job must be [enabled](license_compliance/index.md#enable-license-compliance) for your project. +1. The Dependency Scanning CI/CD job must be [enabled](license_scanning_of_cyclonedx_files/index.md#enable-license-scanning) for your project. 1. Your project must use at least one of the - [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). + [supported languages and package managers](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). When everything is configured, on the left sidebar, select **Secure > License compliance**. 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 1fbe67a62b2..97f9f277776 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -5,13 +5,16 @@ 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 --- -# License scanning of CycloneDX files **(ULTIMATE)** +# 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. +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.** + To detect the licenses in use, License Compliance relies on running the [Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), and analyzing the [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) generated by those jobs. @@ -142,3 +145,22 @@ $ docker run -it --rm -v "$PWD:/my-cyclonedx-sboms" -w /my-cyclonedx-sboms cyclo Validating JSON BOM... BOM validated successfully. ``` + +If the JSON BOM fails validation, for example, because there are duplicate components: + +```shell +Validation failed: Found duplicates at the following index pairs: "(A, B), (C, D)" +#/properties/components/uniqueItems +``` + +This issue can be fixed by updating the CI template to use [jq](https://jqlang.github.io/jq/) to remove the duplicate components from the `gl-sbom-*.cdx.json` report by overriding the job definition that produces the duplicate components. For example, the following removes duplicate components from the `gl-sbom-gem-bundler.cdx.json` report file produced by the `gemnasium-dependency_scanning` job: + +```yaml +include: + - template: Jobs/Dependency-Scanning.gitlab-ci.yml + +gemnasium-dependency_scanning: + after_script: + - 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 +``` diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index c81cf6762e3..53add75ee19 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -4,7 +4,7 @@ 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 --- -# Customer relations management (CRM) **(FREE)** +# Customer relations management (CRM) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. > - In GitLab 14.8 and later, you can [create contacts and organizations only in root groups](https://gitlab.com/gitlab-org/gitlab/-/issues/350634). @@ -157,7 +157,7 @@ organizations using the GraphQL API. ## Issues -If you use [Service Desk](../project/service_desk.md) and create issues from emails, +If you use [Service Desk](../project/service_desk/index.md) and create issues from emails, issues are linked to contacts matching the email addresses in the sender and CC of the email. ### View issues linked to a contact diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 2e26b67170c..0bdbfe79775 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Comments and threads **(FREE)** +# Comments and threads **(FREE ALL)** > - Paginated merge request discussions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. > - Paginated merge request discussions [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. @@ -221,7 +221,7 @@ To change the activity sort order: 1. On the right side of the page, from the **Sort or filter** dropdown list, select the sort order **Newest first** or **Oldest first** (default). -## View description change history **(PREMIUM)** +## View description change history **(PREMIUM ALL)** You can see changes to the description listed in the history. diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index 27fff4bf8e3..e7be5bfb140 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -134,6 +134,15 @@ You then see: - The domains' status of **Verified** or **Unverified**. - The project where the domain has been configured. +### Manage domains in group + +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. 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. + ## Manage enterprise users in a namespace A top-level Owner of a namespace on a paid plan can retrieve information about and diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 04858d8ac34..47f6e0ac1d9 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -11,6 +11,15 @@ This page contains information about the settings that are used on GitLab.com, a See some of these settings on the [instance configuration page](https://gitlab.com/help/instance_configuration) of GitLab.com. +## Email confirmation + +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. + ## Password requirements GitLab.com has the following requirements for passwords on new accounts and password changes: @@ -73,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.md#configure-a-suffix-for-service-desk-alias-email) in project +[custom suffix](../project/service_desk/index.md#configure-a-suffix-for-service-desk-alias-email) in project settings. ## Backups @@ -201,11 +210,14 @@ varies by format: GitLab.com has the following account limits enabled. If a setting is not listed, the default value [is the same as for self-managed instances](../../administration/settings/account_and_limit_settings.md): -| Setting | GitLab.com default | -|-------------------------------|--------------------| -| [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | -| [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GB | -| Maximum attachment size | 100 MB | +| Setting | GitLab.com default | +|--------------------------------------------------------------------------------------------------------------------|--------------------| +| [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | +| [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GB | +| 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 | 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) diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 8bebaae003c..0ccd4512039 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Configure your groups to control group permissions and access. -## Group push rules **(PREMIUM)** +## Group push rules **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in GitLab 12.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. @@ -52,7 +52,7 @@ To change the permitted Git access protocols for a group: 1. Choose the permitted protocols from **Enabled Git access protocols**. 1. Select **Save changes**. -## Restrict group access by IP address **(PREMIUM)** +## Restrict group access by IP address **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. @@ -101,8 +101,9 @@ Keep in mind that restricting group access by IP address has the following impli - IP access restrictions for Git operations via SSH are supported on GitLab SaaS. 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. -## Restrict group access by domain **(PREMIUM)** +## Restrict group access by domain **(PREMIUM ALL)** > - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. > - Support for restricting access to projects in the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. @@ -192,7 +193,7 @@ your group. 1. Clear the **Allow users to request access** checkbox. 1. Select **Save changes**. -## Prevent project forking outside group **(PREMIUM)** +## Prevent project forking outside group **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. @@ -214,7 +215,7 @@ To prevent projects from being forked outside the group: Existing forks are not removed. -## Prevent members from being added to projects in a group **(PREMIUM)** +## Prevent members from being added to projects in a group **(PREMIUM ALL)** As a group Owner, you can prevent any new project membership for all projects in a group, allowing tighter control over project membership. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 15fa5941dc2..e41991f365c 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -5,7 +5,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 --- -# Group-level Kubernetes clusters (certificate-based) (deprecated) **(FREE)** +# Group-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -106,7 +106,7 @@ the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. [More details](../../project/clusters/gitlab_managed_clusters.md#base-domain). -## Environment scopes **(PREMIUM)** +## Environment scopes **(PREMIUM ALL)** When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with @@ -162,7 +162,7 @@ The result is: - The Staging cluster is used for the `deploy to staging` job. - The Production cluster is used for the `deploy to production` job. -## Cluster environments **(PREMIUM)** +## Cluster environments **(PREMIUM ALL)** For a consolidated view of which CI [environments](../../../ci/environments/index.md) are deployed to the Kubernetes cluster, see the documentation for diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 267cdbbebd3..35e8ad27bc3 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Compliance frameworks **(PREMIUM)** +# Compliance frameworks **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. @@ -113,7 +113,7 @@ mutation { } ``` -## Compliance pipelines **(ULTIMATE)** +## Compliance pipelines **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 02f1e7f21e2..9716143f5e2 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -4,7 +4,7 @@ stage: Plan 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 --- -# Contribution analytics **(PREMIUM)** +# Contribution analytics **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 6bd57079c67..1a481641111 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -4,16 +4,16 @@ 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 --- -# Custom group-level project templates **(PREMIUM)** +# Custom group-level project templates **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in GitLab 11.6. -When you create a project, you can [choose from a list of templates](../project/index.md#create-a-project). +When you create a project, you can [choose from a list of templates](../project/index.md). These templates, for things like GitLab Pages or Ruby, populate the new project with a copy of the files contained in the template. This information is identical to the information used by [GitLab project import/export](../project/settings/import_export.md) and can help you start a new project more quickly. -You can [customize the list](../project/index.md#create-a-project) of available templates, so +You can [customize the list](../project/index.md) of available templates, so that all projects in your group have the same list. To do this, you populate a subgroup with the projects you want to use as templates. diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 7aa4695e58b..852d26f3816 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -4,7 +4,7 @@ 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 --- -# Group DevOps Adoption **(ULTIMATE)** +# Group DevOps Adoption **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](../../../policy/experiment-beta-support.md#beta). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333556) in GitLab 14.1. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 47bcd92f134..41231db5964 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epic boards **(PREMIUM)** +# Epic boards **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 5d3bac4f895..7b977dc2026 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Epics **(PREMIUM)** +# Epics **(PREMIUM ALL)** When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. @@ -52,7 +52,7 @@ You can add issues from a different group hierarchy to an epic. To do it, paste the issue URL when [adding an existing issue](manage_epics.md#add-an-existing-issue-to-an-epic). -## Roadmap in epics **(ULTIMATE)** +## Roadmap in epics **(ULTIMATE ALL)** If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that have a start or due date, a visual diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 9ce4a585d14..8b57c1b4d1f 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Linked epics **(ULTIMATE)** +# Linked epics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353473) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `related_epics_widget`. Enabled by default. > - [Feature flag `related_epics_widget`](https://gitlab.com/gitlab-org/gitlab/-/issues/357089) removed in GitLab 15.0. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 8265540cc34..e6116151012 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -5,7 +5,7 @@ group: Product Planning 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 --- -# Manage epics **(PREMIUM)** +# Manage epics **(PREMIUM ALL)** This page collects instructions for all the things you can do with [epics](index.md) or in relation to them. @@ -448,7 +448,7 @@ To reorder issues assigned to an epic: 1. Go to the **Child issues and epics** section. 1. Drag issues into the desired order. -### Move issues between epics **(ULTIMATE)** +### Move issues between epics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. > - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. @@ -508,7 +508,7 @@ For an introduction to epic templates, see [GitLab Epics and Epic Template Tip]( For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/getting-started/104/). -## Multi-level child epics **(ULTIMATE)** +## Multi-level child epics **(ULTIMATE ALL)** You can add any epic that belongs to a group or subgroup of the parent epic's group. New child epics appear at the top of the list of epics in the **Child issues and epics** section. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 154eb467ece..b645ea04038 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -4,7 +4,7 @@ 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 --- -# Migrating GitLab groups **(FREE)** +# Migrating GitLab groups **(FREE ALL)** You can migrate GitLab groups: @@ -64,6 +64,53 @@ groups are in the same GitLab instance. Transferring groups is a faster and more See [epic 6629](https://gitlab.com/groups/gitlab-org/-/epics/6629) for a list of known issues for migrating by direct transfer. +### Estimating migration duration + +Estimating the duration of migration by direct transfer is difficult. The following factors affect migration duration: + +- Hardware and database resources available on the source and destination GitLab instances. More resources on the source and destination instances can result in + shorter migration duration because: + - The source instance receives API requests, and extracts and serializes the entities to export. + - The destination instance runs the jobs and creates the entities in its database. +- Complexity and size of data to be exported. For example, imagine you want to migrate two different projects with 1000 merge requests each. The two projects can take + very different amounts of time to migrate if one of the projects has a lot more attachments, comments, and other items on the merge requests. Therefore, the number + of merge requests on a project is a poor predictor of how long a project will take to migrate. + +There’s no exact formula to reliably estimate a migration. However, the average durations of each pipeline worker importing a project relation can help you to get an idea of how long importing your projects might take: + +| Project resource type | Average time (in seconds) to import a record | +|:----------------------------|:---------------------------------------------| +| Empty Project | 2.4 | +| Repository | 20 | +| Project Attributes | 1.5 | +| Members | 0.2 | +| Labels | 0.1 | +| Milestones | 0.07 | +| Badges | 0.1 | +| Issues | 0.1 | +| Snippets | 0.05 | +| Snippet Repositories | 0.5 | +| Boards | 0.1 | +| Merge Requests | 1 | +| External Pull Requests | 0.5 | +| Protected Branches | 0.1 | +| Project Feature | 0.3 | +| Container Expiration Policy | 0.3 | +| Service Desk Setting | 0.3 | +| Releases | 0.1 | +| CI Pipelines | 0.2 | +| Commit Notes | 0.05 | +| Wiki | 10 | +| Uploads | 0.5 | +| LFS Objects | 0.5 | +| Design | 0.1 | +| Auto DevOps | 0.1 | +| Pipeline Schedules | 0.5 | +| References | 5 | +| Push Rule | 0.1 | + +If you are migrating large projects and encounter problems with timeouts or duration of the migration, see [Reducing migration duration](#reducing-migration-duration). + ### Limits Hardcoded limits apply on migration by direct transfer. @@ -77,7 +124,6 @@ Hardcoded limits apply on migration by direct transfer. | 50 MB | Maximum length an NDJSON row can have. | | 5 minutes | Maximum number of seconds until an empty export status on source instance is raised. | | 8 hours | Time until migration times out. | -| 90 minutes | Time the destination is waiting for export to complete. | You can test the maximum relation size limit using these APIs: @@ -91,8 +137,12 @@ If either API produces files larger than the maximum relation size limit, group After migration: - Private groups and projects stay private. +- Internal groups and projects: + - Stay internal when copied into an internal group unless internal visibility is [restricted](../../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). In that case, the groups and projects become private. + - Become private when copied into a private group. - Public groups and projects: - - Stay public when copied into a public group. + - Stay public when copied into a public group unless public visibility is [restricted](../../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). In that case, the groups and projects become internal. + - Become internal when copied into an internal group unless internal visibility is [restricted](../../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). In that case, the groups and projects become private. - Become private when copied into a private group. If you used a private network on your source instance to hide content from the general public, @@ -429,6 +479,24 @@ You can receive other `404` errors when importing a group, for example: This error indicates a problem transferring from the _source_ instance. To solve this, check that you have met the [prerequisites](#prerequisites) on the source instance. +#### Reducing migration duration + +A single direct transfer migration runs 5 entities (groups or projects) per import at a time, independent of the number of workers available on the destination instance. +That said, having more workers on the destination instance speeds up migration by decreasing the time it takes to import each entity. + +Increasing the number of workers on the destination instance helps reduce the migration duration until the source instance hardware resources are saturated. Exporting and importing relations in batches (proposed in [epic 9036](https://gitlab.com/groups/gitlab-org/-/epics/9036)) will make having enough available workers on +the destination instance even more useful. + +The number of workers on the source instance should be enough to export the 5 concurrent entities in parallel (for each running import). Otherwise, there can be +delays and potential timeouts as the destination is waiting for exported data to become available. + +Distributing projects in different groups helps to avoid timeouts. If several large projects are in the same group, you can: + +1. Move large projects to different groups or subgroups. +1. Start separate migrations each group and subgroup. + +The GitLab UI can only migrate top-level groups. Using the API, you can also migrate subgroups. + ## Migrate groups by uploading an export file (deprecated) > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -581,7 +649,7 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 groups per minute | -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](../../project/import/index.md#automate-group-and-project-import). diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 7ff9648e41e..13fba43f8ef 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.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 --- -# Groups **(FREE)** +# Groups **(FREE ALL)** In GitLab, you use groups to manage one or more related projects at the same time. @@ -27,7 +27,7 @@ organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitla A single top-level group provides insights in your entire organization via a complete [Security Dashboard and Center](../application_security/security_dashboard/index.md), [Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and -[Compliance Report](../compliance/compliance_report/index.md), and +[Compliance center](../compliance/compliance_center/index.md), and [Value stream analytics](../group/value_stream_analytics/index.md). ## Group visibility @@ -63,6 +63,24 @@ This page shows groups that you are a member of: - Through membership of a subgroup's parent group. - Through direct or inherited membership of a project in the group or subgroup. +## View group activity + +To view the activity of a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Activity**. +1. Optional. To filter activity by contribution type, select a tab: + + - **All**: All contributions by group members in the group and group's projects. + - **Push events**: Push events in the group's projects. + - **Merge events**: Accepted merge requests in the group's projects. + - **Issue events**: Issues opened and closed in the group's projects. + - **Epic events**: Epics opened and closed in the group. + - **Comments**: Comments posted by group members in the group's projects. + - **Wiki**: Updates to wiki pages in the group. + - **Designs**: Designs added, updated, and removed in the group's projects. + - **Team**: Group members who joined and left the group's projects. + ## Create a group To create a group: @@ -111,7 +129,7 @@ In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. -## Remove a group immediately **(PREMIUM)** +## Remove a group immediately **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2. > - Enabled delayed deletion by default and removed the option to delete immediately [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. @@ -134,7 +152,7 @@ To immediately remove a group marked for deletion: Your group, its subgroups, projects, and all related resources, including issues and merge requests, are deleted. -## Restore a group **(PREMIUM)** +## Restore a group **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. @@ -231,6 +249,8 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last ## Add users to a group +> Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2. + You can give a user access to all projects in a group. Prerequisite: @@ -242,9 +262,13 @@ Prerequisite: 1. Select **Invite members**. 1. Fill in the fields. - The role applies to all projects in the group. For more information, see [permissions](../permissions.md). - - On the **Access expiration date**, the user can no longer access projects in the group. + - Optional. Select an **Access expiration date**. From that date onward, the + user can no longer access the project. 1. Select **Invite**. +If you selected an access expiration date, the group member gets an email notification +seven days before their access expires. + Members that are not automatically added are displayed on the **Invited** tab. Users can be on this tab because they: @@ -283,7 +307,7 @@ To avoid this problem, GitLab administrators can [ensure removed users cannot in There are two different ways to add a new project to a group: -- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md#create-a-project). +- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md). - While you are creating a project, select a group from the dropdown list.  diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index ab967c8b12c..5cb982a85e4 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -4,7 +4,7 @@ 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 --- -# Insights for groups **(ULTIMATE)** +# Insights for groups **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. @@ -47,8 +47,8 @@ Insights display data from the last 90 days. You can zoom in to display data onl To do this, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: -- To select a later start date, slide the left pause icon to the right. -- To select an earlier end date, slide the right pause icon to the left. +- To change the start date, slide the left pause icon to the left or right. +- To change the end date, slide the right pause icon to the left or right. ### Exclude dimensions from charts diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index cc43ca80801..46ba1747b06 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Issue analytics for groups **(PREMIUM)** +# Issue analytics for groups **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index a4677182bb0..91e69f3a02d 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Iterations **(PREMIUM)** +# Iterations **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1 [with a flag](../../../administration/feature_flags.md) named `group_iterations`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 13.2. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index b7bdf236ff7..743aabd8f4b 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -15,7 +15,7 @@ organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitla A single top-level group provides insights in your entire organization via a complete [Security Dashboard and Center](../application_security/security_dashboard/index.md), [Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and -[Compliance Report](../compliance/compliance_report/index.md), and +[Compliance center](../compliance/compliance_center/index.md), and [Value stream analytics](../group/value_stream_analytics/index.md). ## Add a group README @@ -215,7 +215,7 @@ To disable group mentions: 1. Select **Group mentions are disabled**. 1. Select **Save changes**. -## Export members as CSV **(PREMIUM)** +## Export members as CSV **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. @@ -233,11 +233,10 @@ For members with `Minimal Access` in the selected group, their `Max Role` and `S ## User cap for groups -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7 [with a flag](../../administration/feature_flags.md) named `saas_user_caps`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/9263) in GitLab 16.3. -FLAG: -On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. -This feature is not ready for production use. +For more information about user caps for GitLab self-managed, see [User cap](../../administration/settings/sign_up_restrictions.md#user-cap). When the number of billable members reaches the user cap, new users can't be added to the group without being approved by the group owner. @@ -301,7 +300,17 @@ To approve members that are pending because they've exceeded the user cap: 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. -## Group file templates **(PREMIUM)** +### Known issues + +The user cap cannot be enabled if a group, subgroup, or project is shared externally. If a group, subgroup, +or project is shared externally, it is shared outside of the namespace hierarchy, regardless of its level +in the hierarchy. + +To ensure that the user cap applies when groups, subgroups, or projects are shared externally, restrict group sharing only within the top-level namespace. This ensure that groups in the same top-leve namespace can be invited, and prevents the addition of new users (seats) when the group is shared. + +User cap doesn’t consider whether users are billable or not (e.g., Free Guest Users in Ultimate). In other words, if you set a cap of 500, user caps block new sign-ups after 500 users, regardless of whether those are all consuming paid seats or not. + +## Group file templates **(PREMIUM ALL)** Use group file templates to share a set of templates for common file types with every project in a group. It is analogous to the @@ -323,7 +332,7 @@ To learn how to create templates for issues and merge requests, see Define project templates at a group level by setting a group as the template source. For more information, see [group-level project templates](custom_project_templates.md). -### Enable group file template **(PREMIUM)** +### Enable group file template **(PREMIUM ALL)** To enable group file templates: @@ -333,7 +342,7 @@ To enable group file templates: 1. Choose a project to act as the template repository. 1. Select **Save changes**. -## Group merge checks settings **(PREMIUM)** +## Group merge checks settings **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372040) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) name `support_group_level_merge_checks_setting`. Disabled by default. @@ -404,7 +413,7 @@ To enable this setting: 1. Under **Merge checks**, select **All threads must be resolved**. 1. Select **Save changes**. -## Group merge request approval settings **(PREMIUM)** +## Group merge request approval settings **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. @@ -493,7 +502,10 @@ To disable third-party AI features for a group: 1. Under **Third-party AI services**, uncheck the **Use third-party AI services** checkbox. 1. Select **Save changes**. -## Group activity analytics **(PREMIUM)** +When Code Suggestions are enabled and disabled, an +[audit event](../../administration/audit_events.md#view-audit-events) is created. + +## Group activity analytics **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/experiment-beta-support.md#beta). diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 85fdeeb25c7..7e67bb6ddb5 100644 --- a/doc/user/group/moderate_users.md +++ b/doc/user/group/moderate_users.md @@ -4,7 +4,7 @@ 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 --- -# Moderate users **(FREE)** +# Moderate users **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index f48a027ab2d..17552ceaf88 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -5,7 +5,7 @@ group: Product Planning 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 --- -# Planning hierarchies **(PREMIUM)** +# Planning hierarchies **(PREMIUM ALL)** Planning hierarchies are an integral part of breaking down your work in GitLab. To understand how you can use epics and issues together in hierarchies, remember the following: @@ -31,7 +31,7 @@ graph TD Group_epic --> Project2_Issue1 ``` -### Hierarchies with multi-level epics **(ULTIMATE)** +### Hierarchies with multi-level epics **(ULTIMATE ALL)** With the addition of [multi-level epics](../epics/manage_epics.md#multi-level-child-epics) and up to seven levels of nested epics, you can achieve the following hierarchy: diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index cde19531ed3..abb967ad8b1 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -4,7 +4,7 @@ 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 --- -# Git abuse rate limit **(ULTIMATE)** +# Git abuse rate limit **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 6f5f4905102..3e7bacbb817 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -4,7 +4,7 @@ group: Pipeline Execution 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 --- -# Repositories analytics for groups **(PREMIUM)** +# Repositories analytics for groups **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 9e0ff22eafa..89d461127e7 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Roadmap **(PREMIUM)** +# Roadmap **(PREMIUM ALL)** > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/198062) from GitLab Ultimate to GitLab Premium in 12.9. > - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/5164) and later, the epic bars show epics' title, progress, and completed weight percentage. @@ -150,7 +150,7 @@ the timeline header represent the days of the week. The timeline bar indicates the approximate position of an epic or milestone based on its start and due dates. -## Blocked epics **(ULTIMATE)** +## Blocked epics **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the "blocked" icon. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index f6eb4ad539c..c5f84510c57 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -41,6 +41,9 @@ This section has screenshots for the elements of Azure Active Directory configur  +NOTE: +Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. + ### SCIM mapping Provisioning: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index dd455944bf8..c3edc01fe74 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -5,7 +5,7 @@ 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 --- -# SAML Group Sync **(PREMIUM)** +# SAML Group Sync **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363084) for self-managed instances in GitLab 15.1. @@ -24,10 +24,6 @@ For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu. NOTE: You must include the SAML configuration block on all Sidekiq nodes in addition to Rails application nodes if you use SAML Group Sync and have multiple GitLab nodes, for example in a distributed or highly available architecture. -NOTE: -SAML Group Sync is only supported for the [SAML provider named `saml`](../../../integration/saml.md#configure-gitlab-to-use-multiple-saml-idps). -As a result, SAML Group Sync only supports a single SAML provider. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). - WARNING: To prevent users being accidentally removed from the GitLab group, follow these instructions closely before enabling Group Sync in GitLab. @@ -73,9 +69,9 @@ For example, Azure AD sends the Azure Group Object ID instead of the name. Use t ``` Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` -are not accepted as a source of groups. -See [examples](../../../user/group/saml_sso/example_saml_config.md) -for configuring the required attribute name in the SAML identity provider's settings. +are not accepted as a source of groups. For more information on configuring the +required attribute name in the SAML identity provider's settings, see +[example group SAML and SCIM configurations](../../../user/group/saml_sso/example_saml_config.md). ## Configure SAML Group Links @@ -106,7 +102,83 @@ Users granted: SAML group membership is evaluated each time a user signs in. -### Global SAML group memberships lock **(PREMIUM SELF)** +### Use the API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. + +You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. + +## Microsoft Azure Active Directory integration + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10507) in GitLab 16.3. + +NOTE: +Microsoft has [announced](https://azure.microsoft.com/en-us/updates/azure-ad-is-becoming-microsoft-entra-id/) that Azure Active Directory (AD) is being renamed to Entra ID. + +Azure AD sends up to 150 groups in the groups claim. When users are members of more than 150 groups Azure AD sends a +group overage claim attribute in the SAML response. Then group memberships must be obtained using the Microsoft Graph API. + +To integrate Microsoft Azure AD, you: + +- Configure Azure AD to enable GitLab to communicate with the Microsoft Graph API. +- Configure GitLab. + +### GitLab settings to Azure AD fields + +| GitLab setting | Azure field | +| ============== | ========================================== | +| Tenant ID | Directory (tenant) ID | +| Client ID | Application (client) ID | +| Client Secret | Value (on **Certificates & secrets** page) | + +### Configure Azure AD + +<!-- vale gitlab.SentenceSpacing = NO --> + +1. In the [Azure Portal](https://portal.azure.com), go to **Azure Active Directory > App registrations > All applications**, and select your GitLab SAML application. +1. Under **Essentials**, the **Application (client) ID** and **Directory (tenant) ID** values are displayed. Copy these values, because you need them for the GitLab configuration. +1. In the left navigation, select **Certificates & secrets**. +1. On the **Client secrets** tab, select **New client secret**. + 1. In the **Description** text box, add a description. + 1. In the **Expires** dropdown list, set the expiration date for the credentials. If the secret expires, the GitLab integration will no longer work until the credentials are updated. + 1. To generate the credentials, select **Add**. + 1. Copy the **Value** of the credential. This value is displayed only once, and you need it for the GitLab configuration. +1. In the left navigation, select **API permissions**. +1. Select **Microsoft Graph > Application permissions**. +1. Select the checkboxes **GroupMember.Read.All** and **User.Read.All**. +1. Select **Add permissions** to save. +1. Select **Grant admin consent for `<application_name>`**, then on the confirmation dialog select **Yes**. The **Status** column for both permissions should change to a green check with **Granted for `<application_name>`**. + +<!-- vale gitlab.SentenceSpacing = YES --> + +### Configure GitLab + +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. Select **Settings > SAML SSO**. +1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. +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**. + +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. Select **Admin Area**. +1. Select **Settings > General**. +1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. +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**. + +With this configuration, if a user signs in with SAML and Azure sends a group overage claim in the response, +GitLab initiates a Group Sync job to call the Microsoft Graph API and retrieve the user's group membership. +Then the GitLab Group membership is updated according to SAML Group Links. + +## Global SAML group memberships lock **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386390) in GitLab 15.10. @@ -131,7 +203,7 @@ To enable global group memberships lock: 1. Expand the **Visibility and access controls** section. 1. Ensure the **Lock memberships to SAML synchronization** checkbox is selected. -### Automatic member removal +## Automatic member removal After a group sync, users who are not members of a mapped SAML group are removed from the group. On GitLab.com, users in the top-level group are assigned the @@ -215,23 +287,17 @@ graph TB GitLabGroupD --> |Member|GitLabUserD ``` -#### User that belongs to many SAML groups automatically removed from GitLab group - -When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab -groups if the group claim is missing from the user's SAML assertion. +### User that belongs to many SAML groups automatically removed from GitLab group -Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent -in the user's SAML assertion. +When using Azure AD with SAML, if any user in your organization is a member of more than 150 groups and you use SAML Group Sync, +that user may lose their group memberships. +For more information, see +[Microsoft Group overages](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages). -With an Azure AD premium subscription, you can allow up to 500 group IDs to be sent in a SAML token using the -[Azure AD documentation configuration steps](https://support.esri.com/en/technical-article/000022190). +GitLab has a [Microsoft Azure Active Directory integration](#microsoft-azure-active-directory-integration) that enables SAML Group Sync for organizations +with users in more than 150 groups. This integration uses the Microsoft Graph API to obtain all user memberships and is +not limited to 150 groups. Otherwise, you can work around this issue by changing the [group claims](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#configure-the-azure-ad-application-registration-for-group-attributes) to use the `Groups assigned to the application` option instead. . - -### Use the API - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. - -You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 7795aed5fd0..41c2090f4bc 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -225,8 +225,7 @@ After you set up your identity provider to work with GitLab, you must configure 1. In the **Default membership role** field, select the role to assign to new users. The default role is **Guest**. In [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523) and later, group owners can set a default membership role other than **Guest**. - To do so, [configure the SAML SSO for the group](#configure-gitlab). That role - becomes the starting role of all users added to the group. + That role becomes the starting role of all users added to the group. 1. Select the **Enable SAML authentication for this group** checkbox. 1. Optional. Select: - **Enforce SSO-only authentication for web activity for this group**. @@ -265,6 +264,9 @@ You can pass user information to GitLab as attributes in the SAML assertion. For more information, see the [attributes available for self-managed GitLab instances](../../../integration/saml.md#configure-assertions). +NOTE: +Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. For more information on configuring required attribute names in the SAML identity provider's settings, see [example group SAML and SCIM configurations](../../../user/group/saml_sso/example_saml_config.md). + ### Link SAML to your existing GitLab.com account > **Remember me** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121569) in GitLab 15.7. diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 62c13e8909b..82703893834 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -5,7 +5,7 @@ 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 --- -# Troubleshooting SAML **(FREE)** +# Troubleshooting SAML **(FREE ALL)** This page contains possible solutions for problems you might encounter when using: diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index e4531882fc1..7d2aa8faa99 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -40,41 +40,43 @@ To check if a user's SAML `NameId` matches their SCIM `externalId`: - Administrators can use the Admin Area to [list SCIM identities for a user](../../../administration/admin_area.md#user-identities). - Group owners can see the list of users and the identifier stored for each user in the group SAML SSO Settings page. -- You can use the [SCIM API](../../../api/scim.md) to manually retrieve the `external_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . -- Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `external_uid` to +- You can use the [SCIM API](../../../api/scim.md) to manually retrieve the `extern_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . +- Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `extern_uid` to the value returned as the SAML `NameId`. ## Mismatched SCIM `extern_uid` and SAML `NameId` Whether the value was changed or you need to map to a different field, the following must map to the same field: -- `id` - `externalId` - `NameId` -If the GitLab `extern_uid` doesn't match the SAML `NameId`, it must be updated for the user to sign in. Your identity -provider should be configured to do this update. In some cases the identity provider cannot do the update, for example -when a user lookup fails because of an ID change. +If the GitLab `extern_uid` does not match the SAML `NameId`, you must update the GitLab `extern_uid` to enable the user to sign in. -Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. -GitLab uses these IDs to look up users. If the identity provider does not know the current values for these fields, -that provider may create duplicate users. +Be cautious if you revise the fields used by your SCIM identity provider, typically `externalId`. +Your identity provider should be configured to do this update. +In some cases the identity provider cannot do the update, for example when a user lookup fails. -If the `extern_uid` for a user is not correct, and also doesn't match the SAML `NameID`, either: +GitLab uses these IDs to look up users. +If the identity provider does not know the current values for these fields, +that provider may create duplicate users, or fail to complete expected actions. -- Have users unlink and relink themselves, based on the +To change the identifier values to match: + +1. Have users unlink and relink themselves, based on the [SAML authentication failed: User has already been taken](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) section. -- Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on. -- Use the [SCIM API](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML - `NameId`. To look up a user, you must know the desired value that matches the `NameId` as well as the current - `extern_uid`. +1. Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on. +1. Use the [SAML API](../../../api/saml.md) or [SCIM API](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML + `NameId` or SCIM `externalId`. You must not: - Update these to incorrect values because this causes users to be unable to sign in. - Assign a value to the wrong user because this causes users to be signed in to the wrong account. +Additionally, the user's primary email must match the email in your SCIM identity provider. + ## Change SCIM app When the SCIM app changes: diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 84902a5cbe9..4fb8b293334 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.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 --- -# Subgroups **(FREE)** +# Subgroups **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index dba7a507fef..1e042ab1924 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -5,7 +5,7 @@ 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 --- -# Value stream analytics **(FREE)** +# Value stream analytics **(FREE ALL)** Value stream analytics measures the time it takes to go from an idea to production. @@ -100,7 +100,7 @@ These events play a key role in the duration calculation, which is calculated by To learn what start and end events can be paired, see [Validating start and end events](../../../development/value_stream_analytics.md#validating-start-and-end-events). -### How value stream analytics aggregates data **(PREMIUM)** +### How value stream analytics aggregates data **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335391) in GitLab 14.5. > - Filter by stop date toggle [added](https://gitlab.com/gitlab-org/gitlab/-/issues/352428) in GitLab 14.9 @@ -143,6 +143,9 @@ Each pre-defined stages of value stream analytics is further described in the ta | Review | The median time taken to review a merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | The median time between merging a merge request that has a closing issue pattern until the very first deployment to a [production environment](#how-value-stream-analytics-identifies-the-production-environment). If there isn't a production environment, this is not tracked. | +NOTE: +Value stream analytics works on timestamp data and aggregates only the final start and stop events of the stage. For items that move back and forth between stages multiple times, the stage time is calculated solely from the final events' timestamps. + For information about how value stream analytics calculates each stage, see the [Value stream analytics development guide](../../../development/value_stream_analytics.md). #### Example workflow @@ -264,7 +267,7 @@ Value stream analytics includes the following lifecycle metrics: - **New issues**: Number of new issues created. - **Deploys**: Total number of deployments to production. -### DORA metrics **(ULTIMATE)** +### DORA metrics **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) lead time for changes DORA metric in GitLab 14.5. > - DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in GitLab 14.3. @@ -343,7 +346,7 @@ NOTE: The date range selector filters items by the event time. The event time is when the selected stage finished for the given item. -## View tasks by type **(PREMIUM)** +## View tasks by type **(PREMIUM ALL)** The **Tasks by type** chart displays the cumulative number of issues and merge requests per day for your group. @@ -360,7 +363,7 @@ To view tasks by type: 1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. -## Create a value stream **(PREMIUM)** +## Create a value stream **(PREMIUM ALL)** ### Create a value stream with GitLab default stages @@ -421,7 +424,7 @@ In the example above, two independent value streams are set up for two teams tha The first value stream uses standard timestamp-based events for defining the stages. The second value stream uses label events. -## Edit a value stream **(PREMIUM)** +## Edit a value stream **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267537) in GitLab 13.10. @@ -440,7 +443,7 @@ After you create a value stream, you can customize it to suit your purposes. To 1. Optional. To undo any modifications, select **Restore value stream defaults**. 1. Select **Save Value Stream**. -## Delete a value stream **(PREMIUM)** +## Delete a value stream **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. @@ -453,7 +456,7 @@ To delete a custom value stream:  -## View number of days for a cycle to complete **(PREMIUM)** +## View number of days for a cycle to complete **(PREMIUM ALL)** > - Chart median line [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. > - Totals [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) with averages in GitLab 13.12. diff --git a/doc/user/img/explain_this_vulnerability.png b/doc/user/img/explain_this_vulnerability.png Binary files differdeleted file mode 100644 index bb938241911..00000000000 --- a/doc/user/img/explain_this_vulnerability.png +++ /dev/null diff --git a/doc/user/index.md b/doc/user/index.md index 8d761c88484..490a946a077 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -4,7 +4,7 @@ group: unassigned 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 GitLab **(FREE)** +# Use GitLab **(FREE ALL)** Get to know the GitLab end-to-end workflow. Configure permissions, organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 01911f2b889..5010c2e92a3 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.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 --- -# Connect a cluster to GitLab **(FREE)** +# Connect a cluster to GitLab **(FREE ALL)** The [certificate-based Kubernetes integration with GitLab](../index.md) was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index 4c55a87a52c..cd81f6a1f86 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.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 --- -# Tracking cluster resources managed by GitLab (deprecated) **(FREE)** +# Tracking cluster resources managed by GitLab (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index d0419e08f95..ad587154021 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.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 --- -# Kubernetes clusters **(FREE)** +# Kubernetes clusters **(FREE ALL)** To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/index.md). diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md index d9b849ffccc..cf1b5585a0c 100644 --- a/doc/user/infrastructure/clusters/manage/clusters_health.md +++ b/doc/user/infrastructure/clusters/manage/clusters_health.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../index.md' --- -# Clusters health (removed) **(FREE)** +# 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/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index f07b70dd8e0..2408e16160b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.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 --- -# Install cert-manager with a cluster management project **(FREE)** +# Install cert-manager with a cluster management project **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. > - Support for cert-manager v1.4 was [introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/69405) in GitLab 14.3. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index 1d56e7c1ba1..ee9b2f848fe 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.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 --- -# Install Ingress with a cluster management project **(FREE)** +# Install Ingress with a cluster management project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index e23f5e8745c..cbc23402915 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -4,7 +4,7 @@ group: Runner 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 --- -# Install GitLab Runner with a cluster management project **(FREE)** +# Install GitLab Runner with a cluster management project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.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 bbf8391e8a0..193e3b70fba 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.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 --- -# Install Vault with a cluster management project **(FREE)** +# Install Vault with a cluster management project **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 614e0f5a7e5..1e1372bb035 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.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 --- -# Migrate to the GitLab agent for Kubernetes **(FREE)** +# Migrate to the GitLab agent for Kubernetes **(FREE ALL)** To connect your Kubernetes cluster with GitLab, you can use: diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md index d5376bfbcb1..2161c2ba191 100644 --- a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.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 --- -# GitLab Terraform helpers **(FREE)** +# GitLab Terraform helpers **(FREE ALL)** GitLab provides two helpers to ease your integration with the [GitLab-managed Terraform State](terraform_state.md). diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index f27f1306c31..26b4b66ac63 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.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 --- -# Infrastructure as Code with Terraform and GitLab **(FREE)** +# Infrastructure as Code with Terraform and GitLab **(FREE ALL)** To manage your infrastructure with GitLab, you can use the integration with Terraform to define resources that you can version, reuse, and share: diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 26bb1d16510..24ae3c998f8 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.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 --- -# Terraform integration in merge requests **(FREE)** +# Terraform integration in merge requests **(FREE ALL)** Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the merge request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 31c4ad757c8..4a8f2f11e58 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.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 --- -# GitLab-managed Terraform state **(FREE)** +# GitLab-managed Terraform state **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. > - Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default. diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index 0011e7c9242..404e48d61bf 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.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 --- -# Terraform template recipes **(FREE)** +# Terraform template recipes **(FREE ALL)** You can customize your Terraform integration by adding the recipes on this page to your pipeline. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index d60f20a3713..54f062884ee 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.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 --- -# Infrastructure management **(FREE)** +# Infrastructure management **(FREE ALL)** With the rise of DevOps and SRE approaches, infrastructure management becomes codified, automatable, and software development best practices gain their place around infrastructure diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 51a4499d716..15a3703adbf 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -36,7 +36,7 @@ GitLab tries to match clusters in the following order: To be selected, the cluster must be enabled and match the [environment selector](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). -## Cluster environments **(PREMIUM)** +## Cluster environments **(PREMIUM ALL)** For a consolidated view of which CI [environments](../../../ci/environments/index.md) are deployed to the Kubernetes cluster, see the documentation for diff --git a/doc/user/markdown.md b/doc/user/markdown.md index c3e4f77411c..c724ae465b8 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Flavored Markdown (GLFM) **(FREE)** +# GitLab Flavored Markdown (GLFM) **(FREE ALL)** > The abbreviation [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/24592) from `GFM` to `GLFM` in GitLab 14.10. @@ -215,8 +215,6 @@ For more information, see the [Kroki integration](../administration/integration/ :::TabTitle Rendered Markdown -<!-- vale gitlab.Markdown_emoji = NO --> - Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":monkey:" alt=":monkey:"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/star2.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":star2:" alt=":star2:"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":speech_balloon:" alt=":speech_balloon:">. Well we have a gift for you: <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/zap.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":zap:" alt=":zap:">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/v.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":v:" alt=":v:"> @@ -227,8 +225,6 @@ If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-f Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border:0;padding:0;" title=":thumbsup:" alt=":thumbsup:"> -<!-- vale gitlab.Markdown_emoji = YES --> - :::TabTitle Code ```markdown @@ -691,6 +687,10 @@ For example, a reference like `#123+s` is rendered as URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+s` are also expanded. +To update the rendered references if the assignee, milestone, or health status changed, +edit the comment or description and save it. +For more information, see issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807). + ### Embedding metrics Metric charts can be embedded in GitLab Flavored Markdown. Read diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 6579ecbadbc..f9c242e7c2a 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Objectives and key results (OKR) **(ULTIMATE)** +# Objectives and key results (OKR) **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default. @@ -354,6 +354,80 @@ Prerequisites: By default, child OKRs are ordered by creation date. To reorder them, drag them around. +## Confidential OKRs + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3. + +Confidential OKRs are OKRs visible only to members of a project with +[sufficient permissions](#who-can-see-confidential-okrs). +You can use confidential OKRs to keep security vulnerabilities private or prevent surprises from +leaking out. + +### Make an OKR confidential + +By default, OKRs are public. +You can make an OKR confidential when you create or edit it. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- A **confidential objective** can have only confidential + [child objectives or key results](#child-objectives-and-key-results): + - To make an objective confidential: If it has any child objectives or key results, you must first + make all of them confidential or remove them. + - To make an objective non-confidential: If it has any child objectives or key results, you must + first make all of them non-confidential or remove them. + - To add child objectives or key results to a confidential objective, you must first make them + confidential. + +#### In a new OKR + +When you create a new objective, a checkbox right below the text area is available to mark the +OKR as confidential. + +Check that box and select **Create objective** or **Create key result** to create the OKR. + +#### In an existing OKR + +To change the confidentiality of an existing OKR: + +1. [Open the objective](#view-an-objective) or [key result](#view-a-key-result). +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Turn on confidentiality**. + +### Who can see confidential OKRs + +When an OKR is made confidential, only users with at least the Reporter role for the project have +access to the OKR. +Users with Guest or [Minimal](permissions.md#users-with-minimal-access) roles can't access +the OKR even if they were actively participating before the change. + +However, a user with the **Guest role** can create confidential OKRs, but can only view the ones +that they created themselves. + +Users with the Guest role or non-members can read the confidential OKR if they are assigned to the OKR. +When a Guest user or non-member is unassigned from a confidential OKR, they can no longer view it. + +Confidential OKRs are hidden in search results for users without the necessary permissions. + +### Confidential OKR indicators + +Confidential OKRs are visually different from regular OKRs in a few ways. +Wherever OKRs are listed, you can see the confidential (**{eye-slash}**) icon +next to the OKRs that are marked as confidential. + +If you don't have [enough permissions](#who-can-see-confidential-okrs), +you cannot see confidential OKRs at all. + +Likewise, while inside the OKR, you can see the confidential (**{eye-slash}**) icon right next to +the breadcrumbs. + +Every change from regular to confidential and vice versa, is indicated by a +system note in the OKR's comments, for example: + +> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago +> - **{eye}** Jo Garcia made the issue visible to everyone just now + ## Two-column layout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 3239467ceb6..3f86e945492 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.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 --- -# Operations Dashboard **(PREMIUM)** +# Operations Dashboard **(PREMIUM ALL)** The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 3f8b0761188..0fcc44e8780 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)** +# Composer packages in the Package Registry **(FREE ALL)** > - [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. @@ -38,7 +38,7 @@ Prerequisites: the [Composer specification](https://getcomposer.org/doc/04-schema.md#version). If the version is not valid, for example, it has three dots (`1.0.0.0`), an error (`Validation failed: Version is invalid`) occurs when you publish. -- A valid `composer.json` file. +- A valid `composer.json` file at the project root directory. - The Packages feature is enabled in a GitLab repository. - The project ID, which is on the project's home page. - One of the following token types: @@ -324,6 +324,14 @@ If you committed your `composer.lock`, you could do a `composer install` in CI w In GitLab 14.10 and later, authorization is required for the [downloading a package archive](../../../api/packages/composer.md#download-a-package-archive) endpoint. If you encounter a credentials prompt when you are using `composer install`, follow the instructions in the [install a composer package](#install-a-composer-package) section to create an `auth.json` file. +### Publish fails with `The file composer.json was not found` + +You might see an error that says `The file composer.json was not found`. + +This issue occurs when [configuration requirements for publishing a package](#publish-a-composer-package-by-using-the-api) are not met. + +To resolve the error, commit a `composer.json` file to the project root directory. + ## Supported CLI commands The GitLab Composer repository supports the following Composer CLI commands: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 1ebd59d18fa..72c5a1980b5 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)** +# Conan packages in the Package Registry **(FREE ALL)** > - [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/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index 6a7c92fd924..2aab69877ff 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Authenticate with the Container Registry **(FREE)** +# Authenticate with the Container Registry **(FREE ALL)** <!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> WARNING: diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index 4d74e029cdd..93140e34493 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Build and push container images to the Container Registry **(FREE)** +# Build and push container images to the Container Registry **(FREE ALL)** Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the Container Registry. 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 148fa65d8c7..88a318d0770 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Delete container images from the Container Registry **(FREE)** +# Delete container images from the Container Registry **(FREE ALL)** You can delete container images from your Container Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index f9b1138ed84..3ec5ddb235e 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -4,7 +4,7 @@ group: Container 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 --- -# GitLab Container Registry **(FREE)** +# GitLab Container Registry **(FREE ALL)** > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 110f3ff908c..9ac00445b95 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Reduce Container Registry data transfers **(FREE)** +# Reduce Container Registry data transfers **(FREE ALL)** Depending on the frequency with which images or tags are downloaded from the Container Registry, data transfers can exceed the GitLab.com limit. This page offers several recommendations and tips for 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 e3ca78becf1..fd781847855 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Reduce Container Registry storage **(FREE)** +# Reduce Container Registry storage **(FREE ALL)** Container registries can grow in size over time if you don't manage your registry usage. For example, if you add a large number of images or tags: diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 220e2085637..b7fbeb96202 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)** +# Debian packages in the Package Registry **(FREE ALL)** > - 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. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index ebe87332948..11b67e5cda3 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Dependency Proxy **(FREE)** +# Dependency Proxy **(FREE ALL)** > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) support for private groups in GitLab 13.7. @@ -69,6 +69,7 @@ Prerequisites: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `dependency_proxy_for_private_groups`. Enabled by default. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276777) the feature flag `dependency_proxy_for_private_groups` in GitLab 15.0. +> - Support for group access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362991) in GitLab 16.3. Because the Dependency Proxy is storing Docker images in a space associated with your group, you must authenticate against the Dependency Proxy. @@ -87,6 +88,7 @@ You can authenticate using: - Your GitLab username and password. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. - A [group deploy token](../../../user/project/deploy_tokens/index.md) with the scope set to `read_registry` and `write_registry`. +- A [group access token](../../../user/group/settings/group_access_tokens.md) for the group, with the scope set to `read_registry` and `write_registry`. Users accessing the Dependency Proxy with a personal access token or username and password must have at least the Guest role for the group they pull images from. diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md index 4c625499d07..e24a3d3fa84 100644 --- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Reduce Dependency Proxy Storage **(FREE)** +# Reduce Dependency Proxy Storage **(FREE ALL)** There's no automatic removal process for blobs. Unless you delete them manually, they're stored indefinitely. Since this impacts your diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index d24808674dc..e309ab002c4 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/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 --- -# GitLab Generic Packages Repository **(FREE)** +# GitLab Generic Packages Repository **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `generic_packages`. Enabled by default. > - [Feature flag `generic_packages`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80886) removed in GitLab 14.8. @@ -111,7 +111,9 @@ Example response with attribute `select = package_file`: ### Publishing a package with the same name or version When you publish a package with the same name and version as an existing package, the new package -files are added to the existing package. You can still use the UI or API to access and view the +files are added to the existing package. When you install a generic package that has a duplicate, GitLab downloads the latest version. + +You can use the UI or API to access and view the existing package's older files. To delete these older package revisions, consider using the Packages API or the UI. @@ -125,11 +127,10 @@ or the UI. In the UI: -1. For your group, go to **Settings > Packages and registries**. -1. Expand the **Package Registry** section. -1. Turn on the **Reject duplicates** toggle. -1. Optional. To allow some duplicate packages, in the **Exceptions** box enter a regex pattern that - matches the names and/or versions of packages to allow. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to 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. Your changes are automatically saved. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index f0e10d73d08..52f98ecf4dc 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)** +# Go proxy for GitLab **(FREE ALL)** > - [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/gradle_repository/index.md b/doc/user/packages/gradle_repository/index.md deleted file mode 100644 index 456acc0da59..00000000000 --- a/doc/user/packages/gradle_repository/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../maven_repository/index.md' -remove_date: '2023-08-09' ---- - -This document was moved to [another location](../maven_repository/index.md). - -<!-- This redirect file can be deleted after <2023-08-09>. --> -<!-- 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/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index 21468b9d3bb..0cdaaf8ece0 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -4,7 +4,7 @@ group: Container 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 --- -# Harbor Registry **(FREE)** +# Harbor Registry **(FREE ALL)** You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md) into GitLab and use Harbor as the container registry for your GitLab project to store images. @@ -68,7 +68,7 @@ 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. Select **Settings > Integrations**. 1. Select **Harbor** under **Active integrations**. -1. Clear the **Active** checkbox under **Enable integration**. +1. Under **Enable integration**, clear the **Active** checkbox. 1. Select **Save changes**. The **Operate > Harbor Registry** entry is removed from the sidebar. diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 58c8e17f48b..57aee4fb4ca 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)** +# Helm charts in the Package Registry **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 2084de58bdb..8173a0407f0 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/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 --- -# Packages and Registries **(FREE)** +# Packages and Registries **(FREE ALL)** The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry for a variety of common package managers. You can publish and share diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index f06db7ef1ac..51755eda7bb 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_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 --- -# Maven packages in the Package Registry **(FREE)** +# Maven packages in the Package Registry **(FREE ALL)** Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -480,10 +480,10 @@ To prevent users from publishing duplicate Maven packages, you can use the [Grap In the UI: -1. For your group, go to **Settings > Packages and registries**. -1. Expand the **Package Registry** section. -1. Turn on the **Do not allow duplicates** toggle. -1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to 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. Your changes are automatically saved. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 0fe2b39a591..695193f878a 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_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 --- -# npm packages in the Package Registry **(FREE)** +# npm packages in the Package Registry **(FREE ALL)** For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md). @@ -29,12 +29,13 @@ Do not use authentication methods other than the methods documented here. Undocu Depending on how the package is installed, you may need to adhere to the naming convention. -You can use one of two API endpoints to install packages: +You can use one of three API endpoints to install packages: - **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. +- **Group-level**: Use when you have many npm packages in different projects under the same group or subgroup. - **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -If you plan to install a package through the [project level](#install-from-the-project-level), then you do not have to adhere to the naming convention. +If you plan to install a package through the [project level](#install-from-the-project-level) or [group level](#install-from-the-group-level), then you do not have to adhere to the naming convention. If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name your package with a [scope](https://docs.npmjs.com/misc/scope/). Scoped packages begin with a `@` have the format of `@owner/package-name`. You can set up the scope for your package in the `.npmrc` file and by using the `publishConfig` option in the `package.json`. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index ea9bfd7defb..74daf9fd891 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_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 --- -# NuGet packages in the Package Registry **(FREE)** +# NuGet packages in the Package Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -70,6 +70,7 @@ You can now add a new source to NuGet with: - [Visual Studio](#add-a-source-with-visual-studio) - [.NET CLI](#add-a-source-with-the-net-cli) - [Configuration file](#add-a-source-with-a-configuration-file) +- [Chocolatey CLI](#add-a-source-with-chocolatey-cli) ### Add a source with the NuGet CLI @@ -281,6 +282,22 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Re export GITLAB_PACKAGE_REGISTRY_PASSWORD=<gitlab_personal_access_token or deploy_token> ``` +### Add a source with Chocolatey CLI + +You can add a source feed with the Chocolatey CLI. If you use Chocolatey CLI v1.x, you can add only a NuGet v2 source feed. + +#### Configure a project-level endpoint + +You need a project-level endpoint to publish NuGet packages to the Package Registry. + +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for Chocolatey: + +- Add the Package Registry as a source with `choco`: + + ```shell + choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2'" -u=<gitlab_username or deploy_token_username> -p=<gitlab_personal_access_token or deploy_token> + ``` + ## Publish a NuGet package Prerequisite: @@ -385,6 +402,31 @@ updated: 1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. +### Publish a NuGet package with Chocolatey CLI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2. + +Prerequisite: + +- The project-level Package Registry is a source for Chocolatey. + +To publish a package with the Chocolatey CLI: + +```shell +choco push <package_file> --source <source_url> --api-key <gitlab_personal_access_token, deploy_token or job token> +``` + +In this command: + +- `<package_file>` is your package filename and ends with `.nupkg`. +- `<source_url>` is the URL of the NuGet v2 feed Package Registry. + +For example: + +```shell +choco push MyPackage.1.0.0.nupkg --source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2" --api-key <gitlab_personal_access_token, deploy_token or job token> +``` + ### Publishing a package with the same name or version When you publish a package with the same name or version as an existing package, diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index d06b1ababb8..4d9ad03afde 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_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 --- -# Package Registry **(FREE)** +# Package Registry **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -104,12 +104,14 @@ 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 [Packages 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 ## Reduce storage usage @@ -157,13 +159,29 @@ Registry disables all Package Registry operations. ### Allow anyone to pull from Package Registry -> Introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `package_registry_access_level`. Enabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385994) in GitLab 15.7. -FLAG: -On self-managed GitLab, by default this feature is available. To disable it, -an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `package_registry_access_level`. +To allow anyone to pull from the Package Registry, regardless of project visibility: -If you want to allow anyone (everyone on the internet) to pull from the Package Registry, no matter what the project visibility is, you can use the additional toggle `Allow anyone to pull from Package Registry` that appears when the project visibility is Private or Internal. +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 **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn on the **Allow anyone to pull from Package Registry** toggle. +1. Select **Save changes**. + +Anyone on the internet can access the Package Registry for the project. + +#### Disable allowing anyone to pull + +Prerequisite: + +- You must be an administrator. + +To hide the **Allow anyone to pull from Package Registry** toggle globally: + +- [Change the application setting](../../../api/settings.md#change-application-settings) `package_registry_allow_anyone_to_pull_option` to `false`. + +Anonymous downloads are disabled, even for projects that turned on the **Allow anyone to pull from Package Registry** toggle. Several known issues exist when you allow anyone to pull from the Package Registry: diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index 4882753d6cf..e6251034cb2 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.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 --- -# Reduce Package Registry Storage **(FREE)** +# Reduce Package Registry Storage **(FREE ALL)** Without cleanup, package registries become large over time. When a large number of packages and their assets are added: diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index d2ee5645fc1..d3aa522f780 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The GitLab Package Registry supports different functionalities for each package type. This support includes publishing and pulling packages, request forwarding, managing duplicates, and authentication. -## Publishing packages **(FREE)** +## Publishing packages **(FREE ALL)** Packages can be published to your project, group, or instance. @@ -30,7 +30,7 @@ Packages can be published to your project, group, or instance. | [Go](../go_proxy/index.md) | Y | N | N | | [Ruby gems](../rubygems_registry/index.md) | Y | N | N | -## Pulling packages **(FREE)** +## Pulling packages **(FREE ALL)** Packages can be pulled from your project, group, or instance. @@ -51,7 +51,7 @@ Packages can be pulled from your project, group, or instance. | [Go](../go_proxy/index.md) | Y | N | Y | | [Ruby gems](../rubygems_registry/index.md) | Y | N | N | -## Forwarding requests **(PREMIUM)** +## Forwarding requests **(PREMIUM ALL)** Requests for packages not found in your GitLab project are forwarded to the public registry. For example, Maven Central, npmjs, or PyPI. @@ -89,7 +89,7 @@ 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. -## Allow or prevent duplicates **(FREE)** +## 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. @@ -110,7 +110,7 @@ By default, the GitLab package registry either allows or prevents duplicates bas | [Go](../go_proxy/index.md) | N | | [Ruby gems](../rubygems_registry/index.md) | Y | -## Authentication tokens **(FREE)** +## Authentication tokens **(FREE ALL)** GitLab tokens are used to authenticate with the GitLab Package Registry. @@ -133,7 +133,7 @@ The following tokens are supported: | [Go](../go_proxy/index.md) | Personal access, job tokens, project access | | [Ruby gems](../rubygems_registry/index.md) | Personal access, job tokens, deploy (project or group) | -## Authentication protocols **(FREE)** +## Authentication protocols **(FREE ALL)** The following authentication protocols are supported: @@ -156,7 +156,7 @@ The following authentication protocols are supported: 1. Basic authentication for Maven packages [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212854) in GitLab 16.0. -## Supported hash types **(FREE)** +## Supported hash types **(FREE ALL)** Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md index 94e5af7cc04..8d31399a36b 100644 --- a/doc/user/packages/package_registry/supported_package_managers.md +++ b/doc/user/packages/package_registry/supported_package_managers.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 --- -# Supported package managers **(FREE)** +# Supported package managers **(FREE ALL)** WARNING: Not all package manager formats are ready for production use. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index d23966f26fe..c196e414461 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_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 --- -# PyPI packages in the Package Registry **(FREE)** +# PyPI packages in the Package Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index ae444880b6b..1c898ee6d92 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)** +# Ruby gems in the Package Registry **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in GitLab 13.10. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 3a3409daa6a..cb0516bdc4a 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_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 --- -# Terraform Module Registry **(FREE)** +# Terraform Module Registry **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. > - Infrastructure registry and Terraform Module Registry [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/404075) into a single Terraform Module Registry feature in GitLab 15.11. diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md index eab1e4392e3..a0757e968bc 100644 --- a/doc/user/packages/workflows/build_packages.md +++ b/doc/user/packages/workflows/build_packages.md @@ -51,6 +51,10 @@ Learn how to install and build packages different package formats. ### Install Conan +Prerequisite: + +- You must install Conan version 1.x. Support for Conan version 2 is proposed in [epic 8258](https://gitlab.com/groups/gitlab-org/-/epics/8258). + Download the Conan package manager to your local development environment by following the instructions at [conan.io](https://conan.io/downloads.html). diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 1df244cf0c6..4db77348bd4 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.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 --- -# Store all of your packages in one GitLab project **(FREE)** +# Store all of your packages in one GitLab project **(FREE ALL)** You can store all of your packages in one project's Package Registry. Rather than using a GitLab repository to store code, you can use the repository to store all your packages. diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md index 572cd309e67..1383cd6df27 100644 --- a/doc/user/packages/workflows/working_with_monorepos.md +++ b/doc/user/packages/workflows/working_with_monorepos.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 --- -# Monorepo package management workflows **(FREE)** +# Monorepo package management workflows **(FREE ALL)** One project or Git repository can contain multiple different subprojects or submodules that are all packaged and published individually. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index cf859174c10..d19f98b98ed 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -4,7 +4,7 @@ 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 --- -# Permissions and roles **(FREE)** +# Permissions and roles **(FREE ALL)** When you add a user to a project or group, you assign them a role. The role determines which actions they can take in GitLab. @@ -102,7 +102,7 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (15) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set metadata such as labels, milestones, or assignees when creating an issue | ✓ (15) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Edit metadata such labels, milestones, or assignees for an existing issue | (15) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | @@ -116,10 +116,10 @@ The following table lists project permissions available for each role: | [Issues](project/issues/index.md):<br>Archive [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (1) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | +| [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View allowed and denied licenses | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | +| [License approval policies](../user/compliance/license_approval_policies.md):<br>Manage license policy | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | @@ -250,7 +250,7 @@ The following table lists project permissions available for each role: 20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project. 22. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). -23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator gives those users permission. The administrator can create a [custom role](#custom-roles) through the API and assign that role to the users. +23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](#custom-roles) through the API and assign that role to the users. <!-- markdownlint-enable MD029 --> @@ -284,6 +284,7 @@ More details about the permissions for some project-level features follow. | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | +| Run deployment job for a protected environment | | | ✓ (5) | ✓ (6) | ✓ (6) | ✓ | | View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | @@ -307,6 +308,7 @@ More details about the permissions for some project-level features follow. - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, run for a non-protected branch. 5. If the user is [allowed to merge or push to the protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches). +6. If the user if [part of a group with at least the Reporter role](../ci/environments/protected_environments.md#deployment-only-access-to-protected-environments) <!-- markdownlint-enable MD029 --> @@ -427,7 +429,7 @@ nested groups if you have membership in one of its parents. For more information, see [subgroup memberships](group/subgroups/index.md#subgroup-membership). -## Users with Minimal Access **(PREMIUM)** +## Users with Minimal Access **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. > - Support for inviting users with Minimal Access role [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106438) in GitLab 15.9. @@ -466,13 +468,16 @@ To work around the issue, give these users the Guest role or higher to any proje - [Release permissions](project/releases/index.md#release-permissions) - [Read-only namespaces](../user/read_only_namespaces.md) -## Custom roles **(ULTIMATE)** +## Custom roles **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`. > - [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. + Custom roles allow group members who are assigned the Owner role to create roles specific to the needs of their organization. @@ -482,10 +487,17 @@ For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code 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 update (change status) of the vulnerabilities. +- In GitLab 16.1 and later, you can create a custom role that can view vulnerability reports and change the status of the vulnerabilities. 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: + +- 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. + ### Create a custom role To enable custom roles for your group, a group member with the Owner role: @@ -514,7 +526,7 @@ You can see the required minimal access levels and abilities requirements in the To associate a custom role with an existing group member, a group member with the Owner role: -1. Invites a user to the root group or any subgroup or project in the root +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 diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index e04c61b2c00..06a90af55c7 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -4,7 +4,7 @@ group: Product Analytics info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Product analytics (Experiment) **(ULTIMATE)** +# Product analytics (Experiment) **(ULTIMATE ALL)** > - 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. @@ -94,11 +94,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. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General** -1. Expand **Product Analytics**. -1. In the **Connect to your instance** section, enter the configuration values. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Analytics**. +1. Expand **Configure** and enter the configuration values. 1. Select **Save changes**. ## Instrument a GitLab project diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index b27658e5e41..2694ed5f213 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -5,7 +5,7 @@ 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 --- -# Deleting a user account **(FREE)** +# Deleting a user account **(FREE ALL)** Users can be deleted from a GitLab instance, either by: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 33888e4f06e..83bdf883510 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -4,7 +4,7 @@ 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 --- -# Two-factor authentication **(FREE)** +# Two-factor authentication **(FREE ALL)** Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access your account, they would need your username and password _and_ access to your second factor of authentication. @@ -71,9 +71,12 @@ To enable 2FA with a one-time password: - Cloud-based (recommended because you can restore access if you lose the hardware device): - [Authy](https://authy.com/). - [Duo](https://duo.com/). - - Other: + - 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). + - Other (Free Software) + - [Aegis Authenticator](https://getaegis.app/). + - [FreeOTP](https://freeotp.github.io/). 1. In the application, add a new entry in one of two ways: - Scan the code displayed by GitLab with your device's camera to add the entry automatically. - Enter the details provided to add the entry manually. @@ -114,14 +117,14 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -1. Add the provider configuration: +1. Add the provider configuration. For Linux package installations: @@ -133,7 +136,7 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: gitlab_rails['forti_authenticator_access_token'] = 's3cr3t' ``` - For installations from source: + For self-compiled installations: ```yaml forti_authenticator: @@ -146,7 +149,7 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Save the configuration file. 1. [Reconfigure](../../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) - (Linux package installations) or [restart](../../../administration/restart_gitlab.md#installations-from-source) + (Linux package installations) or [restart](../../../administration/restart_gitlab.md#self-compiled-installations) (self-compiled installations). ### Enable one-time password using Duo @@ -181,14 +184,14 @@ On your GitLab server: sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -1. Add the provider configuration: +1. Add the provider configuration. For Linux package installations: @@ -199,7 +202,7 @@ On your GitLab server: gitlab_rails['duo_auth_hostname'] = '<duo_api_hostname>' ``` - For installations from source: + For self-compiled installations: ```yaml duo_auth: @@ -211,7 +214,7 @@ On your GitLab server: 1. Save the configuration file. 1. For Linux package installations, [reconfigure GitLab](../../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). - For installations from source, [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source). + For self-compiled installations, [restart GitLab](../../../administration/restart_gitlab.md#self-compiled-installations). ### Enable one-time password using FortiToken Cloud @@ -240,14 +243,14 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: sudo editor /etc/gitlab/gitlab.rb ``` - For installations from source: + For self-compiled installations: ```shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -1. Add the provider configuration: +1. Add the provider configuration. For Linux package installations: @@ -257,7 +260,7 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>' ``` - For installations from source: + For self-compiled installations: ```yaml forti_token_cloud: @@ -268,7 +271,7 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Save the configuration file. 1. [Reconfigure](../../../administration/restart_gitlab.md#reconfigure-a-linux-package-installation) (Linux package installations) or - [restart](../../../administration/restart_gitlab.md#installations-from-source) (self-compiled installations). + [restart](../../../administration/restart_gitlab.md#self-compiled-installations) (self-compiled installations). ### Set up a WebAuthn device diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index a90144beb1b..080ab41083b 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)** +# Achievements (Experiment) **(FREE ALL)** > [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. @@ -115,7 +115,7 @@ To supply the avatar file, call the mutation using `curl`: curl "https://gitlab.com/api/graphql" \ -H "Authorization: Bearer <your-pat-token>" \ -H "Content-Type: multipart/form-data" \ - -F operations='{ "query": "mutation ($file: Upload!) { achievementsCreate(input: { namespaceId: \"gid://gitlab/Namespace/<namespace-id>\", name: \"<name>\", description: \"<description>\", avatar: $file }) { achievement { id name description avatarUrl } } }", "variables": { "file": null } }' \ + -F operations='{ "query": "mutation ($file: Upload!) { achievementsCreate(input: { namespaceId: \"gid://gitlab/Namespace/<namespace-id>\", name: \"<name>\", description: \"<description>\", avatar: $file }) { achievement { id name description avatarUrl } } }", "variables": { "file": null } }' \ -F map='{ "0": ["variables.file"] }' \ -F 0='@/path/to/your/file.jpg' ``` @@ -252,7 +252,7 @@ mutation { ## Delete an achievement If you consider you no longer need an achievement, you can delete it. -This will delete all related awarded and revoked instances of the achievement. +This deletes all related awarded and revoked instances of the achievement. Prerequisites: diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index cb56aa8a07a..5e8eb80a1aa 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Active sessions **(FREE)** +# Active sessions **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17867) in GitLab 10.8. diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md index a9db2d268fe..50df5f8fdb4 100644 --- a/doc/user/profile/comment_templates.md +++ b/doc/user/profile/comment_templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Comment templates **(FREE)** +# Comment templates **(FREE ALL)** > - GraphQL support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352956) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. > - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only. @@ -41,6 +41,7 @@ To create a comment template for future use: 1. On the left sidebar, select your avatar. 1. From the dropdown list, select **Preferences**. 1. On the left sidebar, select **Comment templates** (**{comment-lines}**). +1. Select **Add new**. 1. Provide a **Name** for your comment template. 1. Enter the **Content** of your reply. You can use any formatting you use in other GitLab text areas. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index e7f7211aeae..37b2c1a26e6 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Contributions calendar **(FREE)** +# Contributions calendar **(FREE ALL)** The contributions calendar displays a [user's events](#user-contribution-events) from the past 12 months. This includes contributions made in forked and [private](#show-private-contributions-on-your-user-profile-page) repositories. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 32ea9dd2c23..a25260c3db9 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -5,7 +5,7 @@ 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 --- -# User account **(FREE)** +# User account **(FREE ALL)** Each GitLab account has a user profile, which contains information about you and your GitLab activity. @@ -57,6 +57,7 @@ To add new email to your account: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Emails**. +1. Select **Add new email**. 1. In the **Email** text box, enter the new email. 1. Select **Add email address**. 1. Verify your email address with the verification email received. @@ -310,7 +311,8 @@ the maximum number of users you can follow is 300. ### Disable following and being followed by other users -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0 [with a flag](../feature_flags.md) named `disable_follow_users`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325558) in GitLab 16.0 [with a flag](../feature_flags.md) named `disable_follow_users`. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/420620) in GitLab 16.3. You can disable following and being followed by other users. @@ -337,14 +339,33 @@ You can disable searching with Zoekt and use Elasticsearch instead. 1. Clear the **Enable advanced code search** checkbox. 1. Select **Save changes**. -## View your activity +## View a user's activity GitLab tracks [user contribution activity](contributions_calendar.md). -To view a summary of your activity, or the activity of other users: +To view a user's activity: -1. From a user's profile, select **Follow**. +1. Go to the user's profile. 1. In the GitLab menu, select **Activity**. -1. Select the **Followed users** tab. + +A list of **Most Recent Activity** contributions is displayed. + +## View your activity + +To view your activity: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. +1. Select **Activity**. +1. Optional. To filter your activity by contribution type, in the **Your Activity** tab, select a tab: + + - **All**: All contributions you made in your groups and projects. + - **Push events**: Push events you made in your projects. + - **Merge events**: Merge requests you accepted in your projects. + - **Issue events**: Issues you opened and closed in your projects. + - **Comments**: Comments you posted in your projects. + - **Wiki**: Wiki pages you created and updated in your projects. + - **Designs**: Designs you added, updated, and removed in your projects. + - **Team**: Projects you joined and left. ## Session duration @@ -405,5 +426,5 @@ a session if the browser is closed or the existing session expires. - Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Manage [SSH keys](../ssh.md) to access your account via SSH -- Change your [syntax highlighting theme](preferences.md#syntax-highlighting-theme) +- [Change the syntax highlighting theme](preferences.md#change-the-syntax-highlighting-theme) - [View your active sessions](active_sessions.md) and revoke any of them if necessary diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index f378b0ae301..f1310bbb323 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Notification emails **(FREE)** +# Notification emails **(FREE ALL)** > - Enhanced email styling [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78604) in GitLab 14.9 [with a feature flag](../../administration/feature_flags.md) named `enhanced_notify_css`. Disabled by default. > - Enhanced email styling [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/355907) in GitLab 14.9. @@ -199,6 +199,8 @@ Users are notified of the following events: | Two-factor authentication disabled | User | Security email, always sent. | | User added to group | User | Sent when user is added to group. | | User added to project | User | Sent when user is added to project. | +| Group access expired | Group members | Sent when user's access to a group expires in seven days. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3._ | +| Project access expired | Project members | Sent when user's access to a project expires in seven days. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3._ | ## Notifications on issues, merge requests, and epics @@ -331,6 +333,13 @@ The participants are: - Authors of comments on the design. - Anyone that is [mentioned](../discussions/index.md#mentions) in a comment on the design. +## Notifications on group or project access expiration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.3. + +GitLab sends an email notification if a user's access to a group or project expires in seven days. +This reminds group or project members to extend their access duration if they want to. + ## Opt out of all GitLab emails If you no longer wish to receive any email notifications: @@ -389,7 +398,7 @@ For example, an email with the reason `assigned` has this sentence in the footer > You are receiving this email because you have been assigned an item on \<configured GitLab hostname>. -#### On-call alerts notifications **(PREMIUM)** +#### On-call alerts notifications **(PREMIUM ALL)** An [on-call alert](../../operations/incident_management/oncall_schedules.md) notification email can have one of [the alert's](../../operations/incident_management/alerts.md) statuses: @@ -399,7 +408,7 @@ notification email can have one of [the alert's](../../operations/incident_manag - `alert_resolved` - `alert_ignored` -#### Incident escalation notifications **(PREMIUM)** +#### Incident escalation notifications **(PREMIUM ALL)** An [incident escalation](../../operations/incident_management/escalation_policies.md) notification email can have one of [the incident's](../../operations/incident_management/incidents.md) status: @@ -427,3 +436,9 @@ current_user = User.first recipients = NotificationRecipients::BuildService.build_recipients(merge_request, current_user, action: "push_to"); recipients.count recipients.each { |notify| puts notify.user.username } ``` + +### Notifications about failed pipeline that doesn't exist + +If you receive notifications (through email or Slack) regarding a failed pipeline that no longer +exists, double-check to see if you have any duplicate GitLab instances that could have triggered the +message. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index a8231460045..9161f5d4cf6 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -5,7 +5,7 @@ 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 --- -# Personal access tokens **(FREE)** +# Personal access tokens **(FREE ALL)** > - Notifications for expiring tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. > - Token lifetime limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. @@ -51,6 +51,7 @@ You can create as many personal access tokens as you like. 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. +1. Select **Add new token**. 1. Enter a name and expiry date for the token. - The token expires on that date at midnight UTC. - If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 17dea99e5ef..2df2674d539 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -5,96 +5,64 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Profile preferences **(FREE)** +# Profile preferences **(FREE ALL)** -A user's profile preferences page allows the user to customize various aspects -of GitLab to their liking. +You can update your preferences to change the look and feel of GitLab. -To navigate to your profile's preferences: +## Change the color theme -1. On the left sidebar, select your avatar. -1. Select **Preferences**. - -## Navigation theme - -The GitLab navigation theme setting allows you to personalize your GitLab experience. -You can choose from several color themes that add unique colors to the left sidebar. +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. -The default theme is Indigo. You can choose between 10 themes: +To change the color theme: -- Indigo -- Light Indigo -- Blue -- Light Blue -- Green -- Light Green -- Red -- Light Red -- Dark -- Light -- [Dark Mode](#dark-mode) - -## Dark mode - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](../../policy/experiment-beta-support.md#experiment) release. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Color theme** section, select a theme. -GitLab has started work on dark mode! The dark mode Experiment release is available in the -spirit of iteration and the lower expectations of -[Experiment features](../../policy/experiment-beta-support.md#experiment). +### Dark mode -Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). -See the epic for: +> [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). -- A list of known issues. -- Our planned direction and next steps. +Dark mode makes elements on the GitLab UI stand out on a dark background. -If you find an issue that isn't listed, leave a comment on the epic or create a -new issue. +- To turn on Dark mode, Select **Preferences > Color theme > Dark Mode**. -Dark mode is available as a navigation theme, for MVC and compatibility reasons. -[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/219512) -to make it configurable in its own section along with support for -different navigation themes. +Dark mode works only with the **Dark** Syntax highlighting theme. You can report and view issues, send feedback, and track progress in [epic 2092](https://gitlab.com/groups/gitlab-org/-/epics/2902). -Dark theme only works with the **Dark** syntax highlighting theme. +## Change the syntax highlighting theme -## Syntax highlighting theme +> Changing the default syntax highlighting theme for authenticated and unauthenticated users [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.1. -> Changing the default syntax highlighting theme for new users and users who are not signed in [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25129) in GitLab 15.10. +Syntax highlighting is a feature in code editors and IDEs. The highlighter assigns a color to each type of code, such as strings and comments. -GitLab uses the [Rouge Ruby library](https://github.com/rouge-ruby/rouge) -for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) -uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided -[Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for -syntax highlighting. For a list of supported languages, see the documentation of -the respective libraries. +To change the syntax highlighting theme: -Changing this setting allows you to customize the color theme when viewing any -syntax highlighted code on GitLab. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +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. -Introduced in GitLab 13.6, the themes [Solarized](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) also apply to the [Web IDE](../project/web_ide/index.md) and [Snippets](../snippets.md). +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. -You can use an API call to change the default syntax highlighting theme for new users and users -who are not signed in. For more information, see the `default_syntax_highlighting_theme` -in the [list of settings that can be accessed through API calls](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). +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. -## Diff colors +## Change the diff colors -A diff compares the old/removed content with the new/added content (for example, when -[reviewing a merge request](../project/merge_requests/reviews/index.md#review-a-merge-request) or in a -[Markdown inline diff](../markdown.md#inline-diff)). -Typically, the colors red and green are used for removed and added lines in diffs. -The exact colors depend on the selected [syntax highlighting theme](#syntax-highlighting-theme). -The colors may lead to difficulties in case of red-green color blindness. +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. -For this reason, you can customize the following colors: +To change the diff colors: -- Color for removed lines -- Color for added lines +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. Go to the **Diff colors** section. +1. Complete the fields. +1. Select **Save changes**. +1. Optional. Type a color code in the fields. ## Behavior @@ -157,7 +125,8 @@ You can choose one of the following options as the first day of the week: - Sunday - Monday -If you select **System Default**, the [instance default](../../administration/settings/index.md#default-first-day-of-the-week) setting is used. +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). ## Time preferences diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md new file mode 100644 index 00000000000..e593378ce4a --- /dev/null +++ b/doc/user/profile/service_accounts.md @@ -0,0 +1,157 @@ +--- +type: index, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Service accounts **(PREMIUM ALL)** + +A service account is a type of machine user that is not tied to an individual human +user. + +A service account: + +- Does not use a licensed seat. +- Is not a: + - Billable user. + - Bot user. +- Is listed in group membership as a service account. +- Cannot sign into GitLab through the UI. + +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. + +## Create a service account + +The number of service accounts you can create is restricted by the number of service +accounts allowed under your license: + +- On GitLab Free, service accounts are not available. +- On GitLab Premium, you can create one service account for every paid seat you have. +- On GitLab Ultimate, you can create an unlimited number of service accounts. + +How you create an account differs depending on whether you are on GitLab.com or self-managed. + +### GitLab.com + +Prerequisite: + +- You must have the Owner role in a top-level group. + +1. [Create a service account](../../api/groups.md#create-service-account-user). + + This service account is associated only with your top-level group. + +1. [Create a personal access token](../../api/groups.md#create-personal-access-token-for-service-account-user) + 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. + +### Self-managed GitLab + +Prerequisite: + +- You must be an administrator for your self-managed instance. + +1. [Create a service account](../../api/users.md#create-service-account-user). + + 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) + 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. + +## Add a service account to subgroup or project + +In terms of functionality, a service account is the same as an [external user](../../administration/external_users.md) +and has minimal access when you first create it. + +You must manually add the service account to each +[project](../project/members/index.md#add-users-to-a-project) or +[group](../group/index.md#add-users-to-a-group) you want the account to have access to. + +There is no limit to the number of service accounts you can add to a project or group. + +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. + +To add the service account through the API, call the following endpoint: + +```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" +``` + +### Change a service account role in a subgroup or project + +You can change a service account role in a subgroup or project through the UI or the API. + +To use the UI, go to the subgroup's or project's membership list and change the service +account's role. + +To use the API, call the following endpoint: + +```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" +``` + +For more information on the attributes, see the [API documentation on editing a member of a group or project](../../api/members.md#edit-a-member-of-a-group-or-project). + +### Rotate the personal access token + +Prerequisites: + +- For GitLab.com, you must have the Owner role in a top-level group. +- For self-managed GitLab, you must be an administrator for your self-managed instance. + +Use the groups API to [rotate the personal access token](../../api/groups.md#rotate-a-personal-access-token-for-service-account-user) for a service account user. + +### Disable a service account + +You cannot directly disable or delete a service account. Instead, you must: + +1. Remove the service account as a member of all subgroups and projects: + + ```shell + curl --request DELETE --header "PRIVATE-TOKEN: <access_token_id>" "https://gitlab.example.com/api/v4/groups/<group_id>/members/<service_account_id>" + ``` + + For more information, see the [API documentation on removing a member from a group or project](../../api/members.md#remove-a-member-from-a-group-or-project). + +1. Revoke the personal access token using the [UI](personal_access_tokens.md#revoke-a-personal-access-token) or the [API](../../api/personal_access_tokens.md#revoke-a-personal-access-token). + +## Related topics + +- [Billable users](../../subscriptions/self_managed/index.md#billable-users) +- [Associated records](account/delete_account.md#associated-records) +- [Project access tokens - bot users](../project/settings/project_access_tokens.md#bot-users-for-projects) +- [Group access tokens - bot users](../group/settings/group_access_tokens.md#bot-users-for-groups) +- [Internal users](../../development/internal_users.md#internal-users) diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index c57a81c00bf..d8604bc712e 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -4,7 +4,7 @@ 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 --- -# User passwords **(FREE)** +# User passwords **(FREE ALL)** If you use a password to sign in to GitLab, a strong password is very important. A weak or guessable password makes it easier for unauthorized people to log into your account. diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index e0c1ceb7ec5..0bec72d64e8 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -6,7 +6,7 @@ type: reference description: "Autocomplete characters in Markdown fields." --- -# Autocomplete characters **(FREE)** +# Autocomplete characters **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36705) in GitLab 13.9: you can search using the full name in user autocomplete. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index be47d6f18bd..c275d2b39db 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.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 --- -# Badges **(FREE)** +# Badges **(FREE ALL)** Badges are a unified way to present condensed pieces of information about your projects. A badge consists of a small image and a URL that the image points to. @@ -133,6 +133,7 @@ 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. Select **Settings > General**. 1. Expand **Badges**. +1. Select **Add badge**. 1. Under **Link**, enter the URL that the badges should point to. 1. Under **Badge image URL**, enter the URL of the image that should be displayed. 1. Select **Add badge**. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index c4ef6a647db..efa1fad92b8 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,7 +4,7 @@ group: unassigned 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 --- -# Canary deployments **(FREE)** +# Canary deployments **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in GitLab 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index 0c12f7d476b..1f251565d3f 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Changelogs **(FREE)** +# Changelogs **(FREE ALL)** Changelogs are generated based on commit titles and Git trailers. To be included in a changelog, a commit must contain a specific Git trailer. Changelogs are generated diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 9a30cbe94e2..45d3834542b 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.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 --- -# Connect EKS clusters through cluster certificates (deprecated) **(FREE)** +# Connect EKS clusters through cluster certificates (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index aaaa72d282e..5127248baed 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.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 --- -# Connect existing clusters through cluster certificates (deprecated) **(FREE)** +# Connect existing clusters through cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 09dbd70d1bb..a3a7cb35346 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.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 --- -# Connect GKE clusters through cluster certificates (deprecated) **(FREE)** +# Connect GKE clusters through cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 470daf499be..16ad95bb95c 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.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 --- -# Add a cluster using cluster certificates (deprecated) **(FREE)** +# Add a cluster using cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index ff30da2ca98..2b57fa964c0 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_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 --- -# Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE)** +# Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE ALL)** > - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 2ea7ac0f1fd..70c96280e48 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.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 --- -# Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE)** +# Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE ALL)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 537b38dd547..1126e5a7241 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.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 --- -# GitLab-managed clusters (deprecated) **(FREE)** +# GitLab-managed clusters (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index ab6084acd5e..58553fbb1c3 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.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 --- -# Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE)** +# Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index c8f49b1917d..7763cb13cd7 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.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 --- -# Multiple clusters per project with cluster certificates (deprecated) **(FREE)** +# Multiple clusters per project with cluster certificates (deprecated) **(FREE ALL)** > - Introduced in GitLab 10.3 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) from GitLab Premium to GitLab Free in 13.2. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index a985436d67d..7f0fd954d97 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.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 --- -# Runbooks **(FREE)** +# Runbooks **(FREE ALL)** Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 3fec38a61a0..0df0ef977c0 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Intelligence **(FREE)** +# Code Intelligence **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md deleted file mode 100644 index f9244177aa5..00000000000 --- a/doc/user/project/code_owners.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'codeowners/index.md' -remove_date: '2023-07-07' ---- - -This document was moved to [another location](codeowners/index.md). - -<!-- This redirect file can be deleted after <2023-07-07>. --> -<!-- 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/codeowners/index.md b/doc/user/project/codeowners/index.md index 272d59bd6a4..74974958910 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -4,7 +4,7 @@ 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 --- -# Code Owners **(PREMIUM)** +# Code Owners **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -339,8 +339,16 @@ The `Documentation` Code Owners section under the **Approval Rules** area displa ### Allowed to Push -The Code Owner approval and protected branch features do not apply to users who -are **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 +skips the merge request process, the protected-branch features +and Code Owner approvals built into merge requests are also skipped. + +This permission is often granted to accounts associated with +automation ([internal users](../../../development/internal_users.md)) +and release tooling. + +All changes from users _without_ the **Allowed to push** permission must be routed through a merge request. ## Technical Resources diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md index d486b689638..c2fbbe88b6f 100644 --- a/doc/user/project/codeowners/reference.md +++ b/doc/user/project/codeowners/reference.md @@ -4,7 +4,7 @@ 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 --- -# Code Owners syntax and error handling **(PREMIUM)** +# Code Owners syntax and error handling **(PREMIUM ALL)** This page describes the syntax and error handling used in Code Owners files, and provides an example file. @@ -210,6 +210,8 @@ Users can be owners of an entry. Each entry can be owned by ## Error handling in Code Owners +> Error validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216066) in GitLab 16.3. + ### Entries with spaces Paths containing whitespace must be escaped with backslashes: `path\ with\ spaces/*.md`. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8f64fe7dd7d..395873d3107 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy boards (deprecated) **(FREE)** +# Deploy boards (deprecated) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in GitLab 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 4e380d485a8..f0d84616c24 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.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 --- -# Deploy keys **(FREE)** +# Deploy keys **(FREE ALL)** Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys to access a repository from an external host, like a build server or Continuous Integration (CI) server. @@ -85,6 +85,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. +1. Select **Add new key**. 1. Complete the fields. 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** checkbox. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 0b9c42f2a60..41fb0018be9 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.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 --- -# Deploy tokens **(FREE)** +# Deploy tokens **(FREE ALL)** > [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. @@ -95,6 +95,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. +1. Select **Add token**. 1. Complete the fields, and select the desired [scopes](#scope). 1. Select **Create deploy token**. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 3fb338a75ec..4da49c4fb12 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Description templates **(FREE)** +# Description templates **(FREE ALL)** You can define templates to use as descriptions for your [issues](issues/index.md) and [merge requests](merge_requests/index.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.md#use-a-custom-template-for-service-desk-tickets). +- For a [Service Desk email template](service_desk/index.md#use-a-custom-template-for-service-desk-tickets). For description templates to work, they must be: @@ -113,7 +113,7 @@ You can also use the instance template repository for file templates. You might also be interested [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)** +### Set group-level description templates **(PREMIUM ALL)** > - [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. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 4c77323778c..88aa9446787 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -4,7 +4,7 @@ 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 --- -# File Locking **(FREE)** +# File Locking **(FREE ALL)** Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, @@ -190,7 +190,7 @@ Suggested workflow for shared projects: 1. Get your changes reviewed, approved, and merged. 1. Unlock the file. -## Default branch file and directory locks **(PREMIUM)** +## Default branch file and directory locks **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab 8.9. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 698b888a32a..5e67706708d 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Git attributes **(FREE)** +# Git attributes **(FREE ALL)** GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index fbb6d1b329d..ba7d7d39e84 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Syntax Highlighting **(FREE)** +# Syntax Highlighting **(FREE ALL)** GitLab provides syntax highlighting on all files through [Highlight.js](https://github.com/highlightjs/highlight.js/) and the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index b957ff93a4c..0f612d5b222 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -4,7 +4,7 @@ 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 --- -# Import your project from Bitbucket Cloud to GitLab **(FREE)** +# Import your project from Bitbucket Cloud to GitLab **(FREE ALL)** NOTE: The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 6226e4c1296..a80ce95c163 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -4,7 +4,7 @@ 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 --- -# Import your project from Bitbucket Server **(FREE)** +# Import your project from Bitbucket Server **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. @@ -23,7 +23,8 @@ created as private in GitLab as well. ## Import your Bitbucket repositories -> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. +> - Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3. You can import Bitbucket repositories to GitLab. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 35ed7a043d0..30a85a108c9 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -4,7 +4,7 @@ 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 --- -# Migrating from ClearCase **(FREE)** +# Migrating from ClearCase **(FREE ALL)** [ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index fb3416a3492..f5f924ef603 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -4,7 +4,7 @@ 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 --- -# Migrating from CVS **(FREE)** +# Migrating from CVS **(FREE ALL)** [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version control system similar to [SVN](https://subversion.apache.org/). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 18758ba99e6..85c24886687 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -4,7 +4,7 @@ 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 --- -# Import your project from FogBugz to GitLab **(FREE)** +# Import your project from FogBugz to GitLab **(FREE ALL)** > Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 22c89084c56..98457b96dde 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -4,7 +4,7 @@ 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 --- -# Import your project from Gitea to GitLab **(FREE)** +# Import your project from Gitea to GitLab **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. @@ -57,7 +57,7 @@ GitLab access your repositories: 1. Select **Generate Token**. 1. Copy the token hash. 1. Go back to GitLab and provide the token to the Gitea importer. -1. Select **List Your Gitea Repositories** and wait while GitLab reads +1. Select **List your Gitea repositories** and wait while GitLab reads your repositories' information. After it's done, GitLab displays the importer page to select the repositories to import. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index afc36f309be..2079c61da31 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -4,7 +4,7 @@ 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 --- -# Import your project from GitHub to GitLab **(FREE)** +# Import your project from GitHub to GitLab **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10, you no longer need to add any users to the parent group in GitLab to successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** branch protection rule. @@ -203,7 +203,7 @@ After imports are completed, they can be in one of three states: Expand **Details** to see a list of [repository entities](#imported-data) that failed to import. -## Mirror a repository and share pipeline status **(PREMIUM)** +## Mirror a repository and share pipeline status **(PREMIUM ALL)** Depending on your GitLab tier, [repository mirroring](../repository/mirror/index.md) can be set up to keep your imported repository in sync with its GitHub copy. @@ -425,7 +425,7 @@ LoadModule ssl_module lib/httpd/modules/mod_ssl.so </VirtualHost> ``` -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 2b69cd40fc7..26054317441 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -4,7 +4,7 @@ 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 --- -# Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE)** +# Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE ALL)** WARNING: The GitLab.com importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8 diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_button_v12_10.png b/doc/user/project/import/img/jira/import_issues_from_jira_button_v12_10.png Binary files differdeleted file mode 100644 index 3c1dc44df93..00000000000 --- a/doc/user/project/import/img/jira/import_issues_from_jira_button_v12_10.png +++ /dev/null diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_button_v16_3.png b/doc/user/project/import/img/jira/import_issues_from_jira_button_v16_3.png Binary files differnew file mode 100644 index 00000000000..e9b15838a4c --- /dev/null +++ b/doc/user/project/import/img/jira/import_issues_from_jira_button_v16_3.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 6f9c64b73cb..c1d6f5dbcbe 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -4,7 +4,7 @@ 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 --- -# Import and migrate projects **(FREE)** +# Import and migrate projects **(FREE ALL)** If you want to bring existing projects to GitLab or copy GitLab projects to a different location, you can: @@ -147,7 +147,7 @@ repository. For example, if an administrator creates the alias `gitlab` for the `https://gitlab.com/gitlab-org/gitlab`, you can clone the project with `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** The GitLab Professional Services team uses [Congregate](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate) to orchestrate user, group, and project import API calls. With Congregate, you can migrate data to diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index ede9eb244c6..b2092082bf8 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -4,27 +4,21 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import your Jira project issues to GitLab **(FREE)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. +# Import your Jira project issues to GitLab **(FREE ALL)** Using GitLab Jira importer, you can import your Jira issues to GitLab.com or to your self-managed GitLab instance. Jira issues import is an MVC, project-level feature, meaning that issues from multiple Jira projects can be imported into a GitLab project. MVC version imports issue title and description -as well as some other issue metadata as a section in the issue description. +and some other issue metadata as a section in the issue description. ## Known limitations -The information imported into GitLab fields from Jira depends on the version of GitLab: +GitLab imports the following information directly: -- From GitLab 12.10 to GitLab 13.1, only the issue's title and description are imported - directly. -- From GitLab 13.2: - - The issue's labels are also imported directly. - - You're also able to map Jira users to GitLab project members when preparing for the - import. +- The issue's title, description, and labels. +- You can also map Jira users to GitLab project members when preparing for the import. Other Jira issue metadata that is not formally mapped to GitLab issue fields is imported into the GitLab issue's description as plain text. @@ -44,8 +38,6 @@ iterations of the GitLab Jira importer. ## Import Jira issues to GitLab -> New import form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216145) in GitLab 13.2. - NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. @@ -55,7 +47,7 @@ To import Jira issues to a GitLab project: 1. On the **{issues}** **Issues** page, select **Actions** (**{ellipsis_v}**) **> Import from Jira**. -  +  The **Import from Jira** option is only visible if you have the [correct permissions](#prerequisites). diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 980c051eac7..433496ba6c9 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -4,7 +4,7 @@ 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 --- -# Import multiple repositories by uploading a manifest file **(FREE)** +# Import multiple repositories by uploading a manifest file **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. > - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 5f06daef0aa..86981799739 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -4,7 +4,7 @@ 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 --- -# Migrating from Perforce Helix **(FREE)** +# Migrating from Perforce Helix **(FREE ALL)** [Perforce Helix](https://www.perforce.com/) provides a set of tools which also include a centralized, proprietary version control system similar to Git. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index c3c516042f7..5d23ee885bb 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -4,7 +4,7 @@ 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 --- -# Import project from repository by URL **(FREE)** +# Import project from repository by URL **(FREE ALL)** You can import your existing repositories by providing the Git URL. @@ -30,7 +30,7 @@ You can import your existing repositories by providing the Git URL. Your newly created project is displayed. -## Automate group and project import **(PREMIUM)** +## Automate group and project import **(PREMIUM ALL)** For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index da9d31e0ca8..b66e8431f9b 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -4,7 +4,7 @@ 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 --- -# Migrate from TFVC to Git **(FREE)** +# Migrate from TFVC to Git **(FREE ALL)** Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/products/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes diff --git a/doc/user/project/index.md b/doc/user/project/index.md index b7bdf47ae49..478e9c6bf1b 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.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" --- -# Create a project **(FREE)** +# Create a project **(FREE ALL)** You can create a project in many ways in GitLab. @@ -62,7 +62,7 @@ A user who creates a project [from a template](#create-a-project-from-a-built-in Imported objects are labeled as `By <username> on <timestamp> (imported from GitLab)`. For this reason, the creation date of imported objects can be older than the creation date of the user's account. This can lead to objects appearing to have been created by a user before they even had an account. -## Create a project from a custom template **(PREMIUM)** +## Create a project from a custom template **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. @@ -87,7 +87,7 @@ Custom project templates are available at: change the **Visibility Level**. 1. Select **Create project**. -## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** +## Create a project from the HIPAA Audit Protocol template **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 @@ -126,7 +126,7 @@ You cannot use `git push` to create projects with project paths that: Previously used project paths have a redirect. The redirect causes push attempts to redirect requests to the renamed project location, instead of creating a new project. To create a new project for a previously -used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). +used or renamed project, use the UI or the [Projects API](../../api/projects.md#create-project). Prerequisites: diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 533824dd58a..60b23540ac3 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -4,7 +4,7 @@ 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 --- -# Insights for projects **(ULTIMATE)** +# Insights for projects **(ULTIMATE ALL)** Configure project insights to explore data such as: diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 405531abd0d..6005bc48d56 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -4,7 +4,7 @@ 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 --- -# Apple App Store **(FREE)** +# Apple App Store **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed. @@ -32,7 +32,7 @@ GitLab supports enabling the Apple App Store integration at the project level. C 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Apple App Store Connect**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the Apple App Store Connect configuration information: - **Issuer ID**: The Apple App Store Connect issuer ID. - **Key ID**: The key ID of the generated private key. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index edd08f1e3d3..c73563ba162 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -4,7 +4,7 @@ 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 --- -# Asana **(FREE)** +# Asana **(FREE ALL)** The Asana integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 8394687d8f5..9abbe75cc4c 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ 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 --- -# Atlassian Bamboo **(FREE)** +# Atlassian Bamboo **(FREE ALL)** You can automatically trigger builds in Atlassian Bamboo when you push changes to your project in GitLab. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 1796e674b00..048673cd4a2 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ 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 --- -# Bugzilla **(FREE)** +# Bugzilla **(FREE ALL)** [Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing tool. @@ -17,7 +17,7 @@ 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. Select **Settings > Integrations**. 1. Select **Bugzilla**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the project in Bugzilla. diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md index bf2c738049c..7075aca28c2 100644 --- a/doc/user/project/integrations/clickup.md +++ b/doc/user/project/integrations/clickup.md @@ -4,7 +4,7 @@ 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 --- -# ClickUp **(FREE)** +# ClickUp **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1. @@ -14,7 +14,7 @@ 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. Select **Settings > Integrations**. 1. Select **ClickUp**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the ClickUp project to link to this GitLab project. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 9580c924fd1..54d092d2fa9 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,7 +4,7 @@ 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 --- -# Custom issue tracker **(FREE)** +# Custom issue tracker **(FREE ALL)** You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md) with GitLab. If your preferred issue tracker is not listed in the @@ -23,7 +23,7 @@ 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. Select **Settings > Integrations**. 1. Select **Custom issue tracker**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to view all the issues in the custom issue tracker. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 180e39e3254..67f76d48744 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,7 +4,7 @@ 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 --- -# Discord Notifications **(FREE)** +# Discord Notifications **(FREE ALL)** The Discord Notifications integration sends event notifications from GitLab to the channel for which the webhook was created. @@ -24,14 +24,18 @@ and configure it in GitLab. ## Configure created webhook in GitLab +> Event webhook overrides [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125621) in GitLab 16.3. + 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. Select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. -1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. -1. Paste the webhook URL that you copied from the create Discord webhook step. +1. Paste the webhook URL that you [created earlier](#create-webhook) into the **Webhook** field. +1. Select the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. +1. Optionally for each checkbox that you select, enter a new Discord webhook URL that you have [configured](#create-webhook) + to override the default one in the **Webhook** field. 1. Configure the remaining options and select the **Save changes** button. The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index eb3eecaa656..105061efba7 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,7 +4,7 @@ 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 --- -# Emails on push **(FREE)** +# Emails on push **(FREE ALL)** When you enable emails on push, you receive email notifications for every change that is pushed to your project. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d96558579d1..7ee0306e7c0 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,7 +4,7 @@ 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 --- -# Engineering Workflow Management (EWM) **(FREE)** +# Engineering Workflow Management (EWM) **(FREE ALL)** The EWM integration allows you to go from GitLab to EWM work items mentioned in merge request descriptions and commit messages. @@ -17,7 +17,7 @@ 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. Select **Settings > Integrations**. 1. Select **EWM**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the EWM project area. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 98654a3b59f..3f4b110468b 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -4,7 +4,7 @@ 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 --- -# GitHub **(PREMIUM)** +# GitHub **(PREMIUM ALL)** You can update GitHub with pipeline status updates from GitLab. The GitHub integration can help you if you use GitLab for CI/CD. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index bfa8a905699..a082d9aa5be 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,12 +4,12 @@ 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 --- -# GitLab for Slack app **(FREE)** +# GitLab for Slack app **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. NOTE: -This page contains information about configuring the GitLab for Slack app on GitLab.com. For administrator documentation, see [GitLab for Slack app administration](../../admin_area/settings/slack_app.md). +This page contains information about configuring the GitLab for Slack app on GitLab.com. For administrator documentation, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md). The GitLab for Slack app is a native Slack app that provides [slash commands](#slash-commands) and [notifications](#slack-notifications) in your Slack workspace. GitLab links your Slack user with your GitLab user so that any command @@ -176,7 +176,7 @@ The following events are available for Slack notifications: ### GitLab for Slack app does not appear in the list of integrations -The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. +The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). @@ -197,7 +197,7 @@ As a workaround, ensure: ### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack -Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../admin_area/settings/slack_app.md) on your self-managed instance. +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. ### Notifications are not received to a channel diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 4b0f4fe205a..696bb6acf99 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -4,7 +4,7 @@ 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 --- -# Google Play **(FREE)** +# Google Play **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389611) in GitLab 15.11. Feature flag `google_play_integration` removed. @@ -34,7 +34,9 @@ To enable the Google Play integration in GitLab: 1. Select **Google Play**. 1. In **Enable integration**, select the **Active** checkbox. 1. In **Package name**, enter the package name of the app (for example, `com.gitlab.app_name`). +1. Optional. Under **Protected branches and tags only**, select the **Only set variables on protected branches and tags** checkbox. 1. In **Service account key (.JSON)**, drag or upload your key file. +1. Optional. Select **Test settings**. 1. Select **Save changes**. After you enable the integration, the global variables `$SUPPLY_PACKAGE_NAME` and `$SUPPLY_JSON_KEY_DATA` are created for CI/CD use. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 4046869072d..e0d30f63ad9 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ 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 --- -# Google Chat **(FREE)** +# Google Chat **(FREE ALL)** You can configure your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (formerly Google diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 12986cba555..803984f82bf 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -4,7 +4,7 @@ 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 --- -# Harbor **(FREE)** +# Harbor **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. @@ -28,7 +28,7 @@ GitLab supports integrating Harbor projects at the group or project level. Compl 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Harbor**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the Harbor configuration information: - **Harbor URL**: The base URL of Harbor instance which is being linked to this GitLab project. For example, `https://harbor.example.net`. - **Harbor project name**: The project name in the Harbor instance. For example, `testproject`. diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differdeleted file mode 100644 index d8aedf84be5..00000000000 --- a/doc/user/project/integrations/img/slack_setup.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index fd59f54a066..00ae1a0478c 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -4,7 +4,7 @@ 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 --- -# Project integrations **(FREE)** +# Project integrations **(FREE ALL)** You can integrate your GitLab projects with other applications. Integrations are like plugins, and give you the freedom to add @@ -75,16 +75,16 @@ You can configure the following integrations. | [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | -| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | +| [Shimo](shimo.md) (deprecated) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | | [GitLab for Slack app](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | -| [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | +| [Slack notifications](slack.md) (deprecated) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | | [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes | | [Telegram](telegram.md) | Send notifications about project events to Telegram. | **{dotted-circle}** No | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | -| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) (deprecated) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ### Project webhooks diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 7d3c85b2c62..f5084392841 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,7 +4,7 @@ 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 --- -# irker (IRC gateway) **(FREE)** +# irker (IRC gateway) **(FREE ALL)** GitLab provides a way to push update messages to an irker server. After you configure the integration, each push to a project triggers the integration to send data directly diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index a73c0f001f3..9e1de5e3aab 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,7 +4,7 @@ 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 --- -# Mattermost notifications **(FREE)** +# Mattermost notifications **(FREE ALL)** Use the Mattermost notifications integration to send notifications for GitLab events (for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 6a09a1cfbcd..4898d5bd337 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -4,7 +4,7 @@ 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 --- -# Mattermost slash commands **(FREE)** +# Mattermost slash commands **(FREE ALL)** You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, like creating an issue, from a [Mattermost](https://mattermost.com/) chat environment. @@ -34,7 +34,7 @@ you can automatically configure Mattermost slash commands: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. -1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. 1. Select **Add to Mattermost**, and select **Save changes**. ## Configure manually @@ -42,7 +42,7 @@ you can automatically configure Mattermost slash commands: To manually configure slash commands in Mattermost, you must: 1. [Enable custom slash commands in Mattermost](#enable-custom-slash-commands-in-mattermost). - (This step is required only for installations from source.) + This step is required only for self-compiled installations. 1. [Get configuration values from GitLab](#get-configuration-values-from-gitlab). 1. [Create a slash command in Mattermost](#create-a-slash-command-in-mattermost). 1. [Provide the Mattermost token to GitLab](#provide-the-mattermost-token-to-gitlab). diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 3d0b77069a3..b359696c72b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,7 +4,7 @@ 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 --- -# Microsoft Teams notifications **(FREE)** +# Microsoft Teams notifications **(FREE ALL)** You can integrate Microsoft Teams notifications with GitLab and display notifications about GitLab projects in Microsoft Teams. To integrate the services, you must: diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index da09d621d07..fe702766a1d 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,7 +4,7 @@ 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 --- -# Mock CI **(FREE)** +# Mock CI **(FREE ALL)** NOTE: This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index 9a87b5b3110..bf485d73691 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -4,7 +4,7 @@ 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 --- -# Pipeline status emails **(FREE)** +# Pipeline status emails **(FREE ALL)** You can send notifications about pipeline status changes in a group or project to a list of email addresses. diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 7f53f08e808..3697e660deb 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -4,7 +4,7 @@ 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 --- -# Pivotal Tracker **(FREE)** +# Pivotal Tracker **(FREE ALL)** The Pivotal Tracker integration adds commit messages as comments to Pivotal Tracker stories. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index d17e8e6bfca..c0b2591d824 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: 'index.md' --- -# Prometheus (removed) **(FREE)** +# 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 index 848ccbb85f6..e31f3b26e66 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring AWS resources (removed) **(FREE)** +# 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 index ca015d7dc8a..4a0d324932b 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring HAProxy (removed) **(FREE)** +# 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 index ee0b0d1fccb..49345f41514 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Prometheus Metrics library (removed) **(FREE)** +# 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 index 4b8b9b4bc21..f5bbaffa58e 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring Kubernetes (removed) **(FREE)** +# 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 index 995de6a28f3..e38f26710fc 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX (removed) **(FREE)** +# 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 index 03f88e6f7c5..189cf59a514 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX Ingress Controller (removed) **(FREE)** +# 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 index 837be9d1e0a..e4edd63314f 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -6,7 +6,7 @@ remove_date: '2023-08-22' redirect_to: '../../../../operations/index.md' --- -# Monitoring NGINX Ingress Controller with VTS metrics (removed) **(FREE)** +# 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 62703ebfad9..218a036f0a2 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -4,7 +4,7 @@ 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 --- -# Pumble **(FREE)** +# Pumble **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93623) in GitLab 15.3. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 9cb93c2d082..af2c7265f5d 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ 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 --- -# Redmine **(FREE)** +# Redmine **(FREE ALL)** You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: @@ -12,7 +12,7 @@ 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. Select **Settings > Integrations**. 1. Select **Redmine**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the Redmine project to link to this GitLab project. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index a0beb71d83f..2d02a4f631c 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ 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 --- -# ServiceNow **(FREE)** +# ServiceNow **(FREE ALL)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 6fbd246d7f4..b2c85c8cb4c 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w <!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -# Shimo (deprecated) **(FREE)** +# Shimo (deprecated) **(FREE ALL)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 @@ -26,7 +26,7 @@ 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. Select **Settings > Integrations**. 1. Select **Shimo**. -1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. 1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). 1. Select **Save changes**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 55000a0a992..87d7476e42e 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> -# Slack notifications (deprecated) **(FREE)** +# Slack notifications (deprecated) **(FREE ALL)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) in GitLab 15.9 @@ -35,7 +35,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. 1. Select **Slack notifications**. -1. In the **Enable integration** section, select the **Active** checkbox. +1. Under **Enable integration**, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab event to send to Slack as a notification. For a full list, see [Triggers for Slack notifications](#triggers-for-slack-notifications). diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index c1e04f2aa63..78c8180cb4c 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -12,10 +12,10 @@ For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) inst You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, like creating an issue, from a [Slack](https://slack.com/) chat environment. -To use slash commands in Slack, you must configure both Slack and GitLab. +To run slash commands in Slack, you must configure both Slack and GitLab. -GitLab can also send events (such as `issue created`) to Slack as part of the -separately configured [Slack notifications](slack.md). +GitLab can also send events (such as `issue created`) to Slack as part of +[Slack notifications](gitlab_slack_application.md#slack-notifications). For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands). @@ -25,15 +25,15 @@ 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. Select **Settings > Integrations**. -1. Select **Slack slash commands**. Leave this browser tab open. -1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). -1. Enter a trigger command. We suggest you use the project name. - Select **Add Slash Command Integration**. -1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. - In particular, make sure you copy and paste the **URL**. - -  - -1. On the Slack configuration page, select **Save Integration** and copy the **Token**. -1. Go back to the GitLab configuration page and paste in the **Token**. -1. Ensure the **Active** checkbox is selected and select **Save changes**. +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). +1. Enter a slash command trigger name. You could use the project name. +1. Select **Add Slash Command Integration**. +1. In the Slack browser tab: + 1. Complete the fields with information from the GitLab browser tab. + 1. Select **Save Integration** and copy the **Token** value. +1. In the GitLab browser tab: + 1. Paste the token and ensure the **Active** checkbox is selected. + 1. Select **Save changes**. + +You can now run slash commands in Slack. diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index 9d36a16f5fc..d68222d2f94 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -4,7 +4,7 @@ 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 --- -# Telegram **(FREE)** +# Telegram **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122879) in GitLab 16.1. @@ -47,7 +47,7 @@ After you invite the bot to a Telegram channel, you can configure GitLab to send 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Telegram**. -1. In **Enable integration**, select the **Active** checkbox. +1. Under **Enable integration**, select the **Active** checkbox. 1. In **New token**, [paste the token value from the Telegram bot](#create-a-telegram-bot). 1. In the **Trigger** section, select the checkboxes for the GitLab events you want to receive in Telegram. 1. In **Channel identifier**, [paste the Telegram channel identifier](#configure-the-telegram-bot). diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 7d0dd6d2af3..d59bfde5944 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,7 +4,7 @@ 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 --- -# Unify Circuit **(FREE)** +# Unify Circuit **(FREE ALL)** The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 3ba05476e63..370584303f8 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ 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 --- -# Webex Teams **(FREE)** +# Webex Teams **(FREE ALL)** You can configure GitLab to send notifications to a Webex Teams space: diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 8d66f3e48dd..c4dd8dcf812 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -4,7 +4,7 @@ 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 --- -# Webhook events **(FREE)** +# Webhook events **(FREE ALL)** You can configure a [webhook](webhooks.md) in your project that triggers when an event occurs. The following events are supported. @@ -611,6 +611,7 @@ Payload example: } }, "work_in_progress": false, + "draft": false, "assignee": { "name": "User1", "username": "user1", @@ -898,6 +899,7 @@ Payload example: "state": "opened", "blocking_discussions_resolved": true, "work_in_progress": false, + "draft": false, "first_contribution": true, "merge_status": "unchecked", "target_project_id": 14, @@ -983,6 +985,10 @@ Payload example: "previous": null, "current": 1 }, + "draft": { + "previous": true, + "current": false + } "updated_at": { "previous": "2017-09-15 16:50:55 UTC", "current":"2017-09-15 16:52:00 UTC" @@ -1454,6 +1460,19 @@ Payload example: "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", "visibility_level": 20 }, + "project":{ + "id": 380, + "name": "Gitlab Test", + "description": "Atque in sunt eos similique dolores voluptatem.", + "web_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test", + "avatar_url": null, + "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", + "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", + "namespace": "Gitlab Org", + "visibility_level": 20, + "path_with_namespace": "gitlab-org/gitlab-test", + "default_branch": "master" + }, "runner": { "active": true, "runner_type": "project_type", @@ -1466,6 +1485,15 @@ Payload example: ] }, "environment": null + "source_pipeline":{ + "project":{ + "id": 41, + "web_url": "https://gitlab.example.com/gitlab-org/upstream-project", + "path_with_namespace": "gitlab-org/upstream-project" + }, + "pipeline_id": 30, + "job_id": 3401 + }, } ``` @@ -1547,7 +1575,7 @@ Payload example: } ``` -## Group member events **(PREMIUM)** +## Group member events **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. @@ -1642,7 +1670,7 @@ Payload example: } ``` -## Subgroup events **(PREMIUM)** +## Subgroup events **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 9f24f3b49ff..fe3d5e015a6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -4,7 +4,7 @@ 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 --- -# Webhooks **(FREE)** +# Webhooks **(FREE ALL)** [Webhooks](https://en.wikipedia.org/wiki/Webhook) are custom HTTP callbacks that you define. They are usually triggered by an @@ -28,7 +28,7 @@ listens for specific [events](#events) and GitLab sends a POST request with data Usually, you set up your own [webhook receiver](#create-an-example-webhook-receiver) to receive information from GitLab and send it to another app, according to your requirements. -We have a [built-in receiver](slack.md) +We have a [built-in receiver](gitlab_slack_application.md#slack-notifications) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications per project. GitLab.com enforces [webhook limits](../../../user/gitlab_com/index.md#webhooks), @@ -37,7 +37,7 @@ including: - The maximum number of webhooks and their size, both per project and per group. - The number of webhook calls per minute. -## Group webhooks **(PREMIUM)** +## 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 @@ -55,6 +55,7 @@ specific to a group, including: To configure a webhook for a project or group: 1. In your project or group, on the left sidebar, select **Settings > Webhooks**. +1. Select **Add new webhook**. 1. In **URL**, enter the URL of the webhook endpoint. The URL must be percent-encoded if it contains one or more special characters. 1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. @@ -309,6 +310,7 @@ These public tools include: - [Beeceptor](https://beeceptor.com) to create a temporary HTTPS endpoint and inspect incoming payloads - [Webhook.site](https://webhook.site) to review incoming payloads +- [Webhook Tester](https://webhook-test.com) to inspect and debug incoming payloads ### GitLab Development Kit (GDK) @@ -378,4 +380,11 @@ If you're receiving multiple webhook requests, the webhook might have timed out. GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout). -If a webhook is not triggered, the webhook might be [automatically disabled](#failing-webhooks). +### Webhook is not triggered + +> Webhooks not triggered in Silent Mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393639) in GitLab 16.3. + +If a webhook is not triggered, check that: + +- The webhook was not [automatically disabled](#failing-webhooks). +- The GitLab instance is not in [Silent Mode](../../../administration/silent_mode/index.md). diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 8845aa8fdfd..651c1a15b7a 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ 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 --- -# YouTrack **(FREE)** +# YouTrack **(FREE ALL)** JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project management platform. @@ -17,7 +17,7 @@ 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. Select **Settings > Integrations**. 1. Select **YouTrack**. -1. Select the checkbox under **Enable integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Fill in the required fields: - **Project URL**: The URL to the project in YouTrack. - **Issue URL**: The URL to view an issue in the YouTrack project. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index b14b9eac9da..e42b0a032fd 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w <!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -# ZenTao (deprecated) **(PREMIUM)** +# ZenTao (deprecated) **(PREMIUM ALL)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7 @@ -43,7 +43,7 @@ Complete these steps in GitLab: 1. Go to your project and select **Settings > Integrations**. 1. Select **ZenTao**. -1. Turn on the **Active** toggle under **Enable Integration**. +1. Under **Enable integration**, select the **Active** checkbox. 1. Provide the ZenTao configuration information: - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index bca1ee5245c..8e3310d3234 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Issue boards **(FREE)** +# Issue boards **(FREE ALL)** The issue board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. @@ -253,12 +253,12 @@ Users on GitLab Free can use a single group issue board. GitLab issue boards are available on the GitLab Free tier, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### Configurable issue boards **(PREMIUM)** +### Configurable issue boards **(PREMIUM ALL)** > - Setting current iteration as scope [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196804) in GitLab 13.8. > - Moved to GitLab Premium in 13.9. -An issue board can be associated with a [milestone](milestones/index.md#milestones), +An issue board can be associated with a [milestone](milestones/index.md), [labels](labels.md), assignee, weight, and current [iteration](../group/iterations/index.md), which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need. @@ -277,7 +277,7 @@ selecting **View scope**. Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of the configurable issue board feature. -### Sum of issue weights **(PREMIUM)** +### Sum of issue weights **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -287,7 +287,7 @@ especially in combination with [assignee lists](#assignee-lists).  -### Assignee lists **(PREMIUM)** +### Assignee lists **(PREMIUM ALL)** As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. @@ -310,7 +310,7 @@ To remove an assignee list, just as with a label list, select the trash icon.  -### Milestone lists **(PREMIUM)** +### Milestone lists **(PREMIUM ALL)** You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. @@ -332,7 +332,7 @@ As in other list types, select the trash icon to remove a list.  -### Iteration lists **(PREMIUM)** +### Iteration lists **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11 [with a flag](../../administration/feature_flags.md) named `iteration_board_lists`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75404) in GitLab 14.6. Feature flag `iteration_board_lists` removed. @@ -355,7 +355,7 @@ to and from a iteration list to manipulate the iteration of the dragged issues.  -### Group issues in swimlanes **(PREMIUM)** +### Group issues in swimlanes **(PREMIUM ALL)** > - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in GitLab 13.6. > - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. @@ -401,7 +401,7 @@ You can also [drag issues](#move-issues-and-lists) to change their position and  -## Work in progress limits **(PREMIUM)** +## Work in progress limits **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -428,7 +428,7 @@ To set a WIP limit for a list, in an issue board: 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. -## Blocked issues **(PREMIUM)** +## Blocked issues **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10: View blocking issues when hovering over the "blocked" icon. diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index d286e784e0a..bb8f0ccd186 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Associate a Zoom meeting with an issue **(FREE)** +# Associate a Zoom meeting with an issue **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 6c2e6cb2132..0b8f6cc33fc 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -4,10 +4,10 @@ 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 --- -# Confidential issues **(FREE)** +# Confidential issues **(FREE ALL)** Confidential issues are [issues](index.md) visible only to members of a project with -[sufficient permissions](#permissions-and-access-to-confidential-issues). +[sufficient permissions](#who-can-see-confidential-issues). Confidential issues can be used by open source projects and companies alike to keep security vulnerabilities private or prevent surprises from leaking out. @@ -15,6 +15,13 @@ keep security vulnerabilities private or prevent surprises from leaking out. You can make an issue confidential when you create or edit an issue. +Prerequisites: + +- You must have at least the Reporter role for the project. +- If the issue you want to make confidential has any child [tasks](../../tasks.md), + you must first make all the child tasks confidential. + A confidential issue can have only confidential children. + ### In a new issue When you create a new issue, a checkbox right below the text area is available @@ -51,63 +58,40 @@ for the project have access to the issue. Users with Guest or [Minimal](../../permissions.md#users-with-minimal-access) roles can't access the issue even if they were actively participating before the change. +However, a user with the **Guest role** can create confidential issues, but can only view the ones +that they created themselves. + +Users with the Guest role or non-members can read the confidential issue if they are assigned to the issue. +When a Guest user or non-member is unassigned from a confidential issue, they can no longer view it. + +Confidential issues are hidden in search results for users without the necessary permissions. + ## Confidential issue indicators Confidential issues are visually different from regular issues in a few ways. -In the issues index page view, you can see the confidential (**{eye-slash}**) icon -next to the issues that are marked as confidential: - - +In the issues list and boards, you can see the confidential (**{eye-slash}**) icon +next to issues marked as confidential. -If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +If you don't have [enough permissions](#who-can-see-confidential-issues), you cannot see confidential issues at all. Likewise, while inside the issue, you can see the confidential (**{eye-slash}**) icon right next to the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential. - - There is also an indicator on the sidebar denoting confidentiality. -| Confidential issue | Not confidential issue | -| :-----------: | :----------: | -|  |  | - Every change from regular to confidential and vice versa, is indicated by a -system note in the issue's comments: +system note in the issue's comments, for example: -- **{eye-slash}** The issue is made confidential. -- **{eye}** The issue is made public. - - +> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago +> - **{eye}** Jo Garcia made the issue visible to everyone just now ## Merge requests for confidential issues Although you can create confidential issues (and make existing issues confidential) in a public project, you cannot make confidential merge requests. Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) that prevent leaks of private data. -## Permissions and access to confidential issues - -Access to confidential issues is by one of two routes. The general rule -is that confidential issues are visible only to members of a project with at -least the **Reporter role**. - -However, a user with the **Guest role** can create -confidential issues, but can only view the ones that they created themselves. - -Users with the Guest role or non-members can read the confidential issue if they are assigned to the issue. -When a Guest user or non-member is unassigned from a confidential issue, -they can no longer view it. - -Confidential issues are hidden in search results for unprivileged users. -For example, here's what a user with the Maintainer role and the Guest role -sees in the project's search results: - -| Maintainer role | Guest role | -|:----------------|:-----------| -|  |  | - ## Related topics - [Merge requests for confidential issues](../merge_requests/confidential.md) diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 8cc9ab71ca7..3014b088fd6 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create an issue **(FREE)** +# Create an issue **(FREE ALL)** When you create an issue, you are prompted to enter the fields of the issue. If you know the values you want to assign to an issue, you can use @@ -192,7 +192,7 @@ To create an issue in the GitLab project: ## Using Service Desk -To offer email support, enable [Service Desk](../service_desk.md) for your project. +To offer email support, enable [Service Desk](../service_desk/index.md) for your project. Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index f1f41de7cb4..b3fe7da4280 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Crosslinking issues **(FREE)** +# Crosslinking issues **(FREE ALL)** There are several ways to mention an issue or make [issues](index.md) appear in each other's [Linked issues](related_issues.md) section. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 9b131372672..86370cab963 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -4,7 +4,7 @@ group: unassigned 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)** +# Export issues to CSV **(FREE ALL)** > Moved to GitLab Free in 12.10. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index d23650e973a..9770c333cdd 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -4,7 +4,7 @@ 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 --- -# Importing issues from CSV **(FREE)** +# Importing issues from CSV **(FREE ALL)** You can import issues to a project by uploading a CSV file with the following columns: diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 6013abc4892..4068083cd1e 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Design management **(FREE)** +# 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. @@ -44,7 +44,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. A GitLab administrator can verify the storage type of a project by going to **Admin Area > Projects** and then selecting the project in question. A project can be identified as - hashed-stored if its **Gitaly relative path** contains `@hashed`. + hashed-stored if the value of the **Relative path** field contains `@hashed`. If the requirements are not met, you are notified in the **Designs** section. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 63b60e4538f..322d603aced 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Due dates **(FREE)** +# Due dates **(FREE ALL)** Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are shipped on time. Users need at least the Reporter role diff --git a/doc/user/project/issues/img/confidential_issues_index_page.png b/doc/user/project/issues/img/confidential_issues_index_page.png Binary files differdeleted file mode 100644 index 16979bf9ac2..00000000000 --- a/doc/user/project/issues/img/confidential_issues_index_page.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_issue_page.png b/doc/user/project/issues/img/confidential_issues_issue_page.png Binary files differdeleted file mode 100644 index b349149aa98..00000000000 --- a/doc/user/project/issues/img/confidential_issues_issue_page.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_search_guest.png b/doc/user/project/issues/img/confidential_issues_search_guest.png Binary files differdeleted file mode 100644 index dc1b4ba8ad7..00000000000 --- a/doc/user/project/issues/img/confidential_issues_search_guest.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_search_master.png b/doc/user/project/issues/img/confidential_issues_search_master.png Binary files differdeleted file mode 100644 index fc01f4da9db..00000000000 --- a/doc/user/project/issues/img/confidential_issues_search_master.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png b/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png Binary files differdeleted file mode 100644 index e448f609112..00000000000 --- a/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/sidebar_confidential_issue.png b/doc/user/project/issues/img/sidebar_confidential_issue.png Binary files differdeleted file mode 100644 index 0ef61c7f1b0..00000000000 --- a/doc/user/project/issues/img/sidebar_confidential_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/sidebar_not_confidential_issue.png b/doc/user/project/issues/img/sidebar_not_confidential_issue.png Binary files differdeleted file mode 100644 index c09f8204b37..00000000000 --- a/doc/user/project/issues/img/sidebar_not_confidential_issue.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index b2cc555d3b7..0b64328fe03 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Issues **(FREE)** +# Issues **(FREE ALL)** Use issues to collaborate on ideas, solve problems, and plan work. Share and discuss proposals with your team and with outside collaborators. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 05c348acf58..b1a1390d3d2 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Issue weight **(PREMIUM)** +# Issue weight **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 6bf8e2eeb97..02cefaa47ef 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Manage issues **(FREE)** +# Manage issues **(FREE ALL)** After you create an issue, you can start working with it. @@ -71,8 +71,9 @@ When bulk editing issues in a project, you can edit the following attributes: - [Health status](#health-status) - [Notification](../../profile/notifications.md) subscription - [Iteration](../../group/iterations/index.md) +- [Confidentiality](confidential_issues.md) -### Bulk edit issues from a group **(PREMIUM)** +### Bulk edit issues from a group **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -388,7 +389,7 @@ Alternatively: 1. Select **Edit title and description** (**{pencil}**). 1. Select **Delete issue**. -## Promote an issue to an epic **(PREMIUM)** +## Promote an issue to an epic **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. > - Moved from GitLab Ultimate to GitLab Premium in 12.8. @@ -414,7 +415,7 @@ Read more about [promoting an issues to epics](../../group/epics/manage_epics.md You can use the `/promote_to_incident` [quick action](../quick_actions.md) to promote the issue to an [incident](../../../operations/incident_management/incidents.md). -## Add an issue to an iteration **(PREMIUM)** +## Add an issue to an iteration **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. > - Moved to GitLab Premium in 13.9. @@ -565,7 +566,7 @@ As you type in the title text box of the **New issue** page, GitLab searches tit across all issues in the current project. Only issues you have access to are returned. Up to five similar issues, sorted by most recently updated, are displayed below the title text box. -## Health status **(ULTIMATE)** +## Health status **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in GitLab 12.10. > - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab 13.4 and later. @@ -606,7 +607,7 @@ until the issue is reopened. You can also set and clear health statuses using the `/health_status` and `/clear_health_status` [quick actions](../quick_actions.md#issues-merge-requests-and-epics). -## Publish an issue **(ULTIMATE)** +## Publish an issue **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.1. diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 59555e1f675..3ec3b72b173 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Multiple assignees for issues **(PREMIUM)** +# Multiple assignees for issues **(PREMIUM ALL)** > Moved from Starter to Premium in GitLab 13.9. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 43acaaf9c2f..10c7899ac30 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,7 +4,7 @@ group: Product Planning 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 --- -# Linked issues **(FREE)** +# Linked issues **(FREE ALL)** > The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) from GitLab Premium to GitLab Free in 13.4. @@ -70,7 +70,7 @@ Due to the bi-directional relationship, the relationship no longer appears in ei Access our [permissions](../../permissions.md) page for more information. -## Blocking issues **(PREMIUM)** +## Blocking issues **(PREMIUM ALL)** When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or **is blocked by** another issue. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 4c0566c2386..c365bfa5a52 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -4,12 +4,12 @@ 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 --- -# Sorting and ordering issue lists **(FREE)** +# Sorting and ordering issue lists **(FREE ALL)** You can sort a list of issues several ways. The available sorting options can change based on the context of the list. -## Sorting by blocking issues **(PREMIUM)** +## Sorting by blocking issues **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. @@ -105,7 +105,7 @@ title in this order: - Numbers - Letters: first Latin, then accented (for example, `ö`) -## Sorting by health status **(ULTIMATE)** +## Sorting by health status **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377841) in GitLab 15.7. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 7f98b62cabf..4daaaf72683 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Labels **(FREE)** +# Labels **(FREE ALL)** As your count of issues, merge requests, and epics grows in GitLab, it gets more challenging to keep track of those items. Especially as your organization grows from just a few people to @@ -153,7 +153,7 @@ To create a group label: a specific color in the **Background color** field. 1. Select **Create label**. -### Create a group label from an epic **(PREMIUM)** +### Create a group label from an epic **(PREMIUM ALL)** You can also create a new group label from an epic. Labels you create this way belong to the same group as the epic. @@ -317,7 +317,7 @@ The following labels are created: - `suggestion` - `support` -## Scoped labels **(PREMIUM)** +## Scoped labels **(PREMIUM ALL)** Teams can use scoped labels to annotate issues, merge requests, and epics with mutually exclusive labels. By preventing certain labels from being used together, you can create more complex workflows. @@ -455,6 +455,13 @@ The labels higher in the list get higher priority. To learn what happens when you sort by priority or label priority, see [Sorting and ordering issue lists](issues/sorting_issue_lists.md). +## Related topics + +Practice working with labels in the following tutorials: + +- [Set up a single project for issue triage](../../tutorials/issue_triage/index.md) +- [Set up issue boards for team hand-off](../../tutorials/boards_for_teams/index.md) + ## Troubleshooting ### Some label titles end with `_duplicate<number>` diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 37b24cda5aa..1e9bd307333 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.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 --- -# Members of a project **(FREE)** +# Members of a project **(FREE ALL)** Members are the users and groups who have access to your project. @@ -79,7 +79,7 @@ and rights into the group or project. | View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | | View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | | Be shared into other groups | ✓ | | | | -| Be shared into other projects | ✓ | ✓ | | | +| Be shared into other projects | ✓ | ✓ | ✓ | ✓ | | Share the group with other members | ✓ | ✓ | ✓ | ✓ | In the following example, `User` is a: @@ -108,6 +108,7 @@ graph TD > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. +> - Expiring access email notification [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12704) in GitLab 16.2. Add users to a project so they become direct members and have permission to perform actions. @@ -130,6 +131,9 @@ To add a user to a project: 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. + If you selected an access expiration date, the project member gets an email notification + seven days before their access expires. + WARNING: If you give a member the Maintainer role and select an expiration date, that member has full permissions for the time they are in the role. This includes the ability diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 15c5935648f..3780018bf11 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.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 --- -# Share a project with a group **(FREE)** +# Share a project with a group **(FREE ALL)** When you want a group to have access to your project, you can invite [a group](../../group/index.md) to the project. @@ -30,7 +30,7 @@ In addition: - You must be a member of the group or the subgroup being invited. -- The [visibility level](../../public_access.md#project-and-group-visibility) of the group you're inviting +- The [visibility level](../../public_access.md) of the group you're inviting must be at least as restrictive as that of the project. For example, you can invite: - A _private_ group to a _private_ project - A _private_ group to an _internal_ project. diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md new file mode 100644 index 00000000000..c1aa729d8c5 --- /dev/null +++ b/doc/user/project/merge_requests/ai_in_merge_requests.md @@ -0,0 +1,120 @@ +--- +stage: Create +group: Code Review +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 +--- + +# AI/ML powered features in merge requests + +AI-assisted features in merge requests are designed to provide contextually relevant information during the lifecycle of a merge request. + +Additional information on enabling these features and maturity can be found in our [AI/ML Overview](../../ai_features.md). + +## Fill in merge request templates **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10591) in GitLab 16.3 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +Merge requests in projects often have [templates](../description_templates.md#create-a-merge-request-template) defined that need to be filled out. This helps reviewers and other users understand the purpose and changes a merge request might propose. + +When creating a merge request you can now choose to generate a description for the merge request based on the contents of the template. This fills in the template and replaces the current contents of the description. + +To generate the description: + +1. Create a new merge request, go to the **Description** field. +1. Select **AI Actions** (**{tanuki}**). +1. Select **Fill in merge request template**. + +The updated description is applied to the box. You can edit or revise this description before you finish creating your merge request. + +Provide feedback on this experimental feature in [issue 416537](https://gitlab.com/gitlab-org/gitlab/-/issues/416537). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Title of the merge request +- Contents of the description +- Source branch name +- Target branch name + +## Summarize merge request changes **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10401) in GitLab 16.2 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +These summaries are automatically generated. They are available on the merge request page in the **Merge request summaries** dialog, the To-Do list, and in email notifications. + +Provide feedback on this experimental feature in [issue 408726](https://gitlab.com/gitlab-org/gitlab/-/issues/408726). + +**Data usage**: The diff of changes between the source branch's head and the target branch is sent to the large language model. + +## Summarize my merge request review **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10466) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +When you've completed your review of a merge request and are ready to [submit your review](reviews/index.md#submit-a-review), you can have a summary generated for you. + +To generate the summary: + +1. When you are ready to submit your review, select **Finish review**. +1. Select **AI Actions** (**{tanuki}**). +1. Select **Summarize my code review**. + +The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. + +Merge request review summaries are also automatically generated when you submit your review. These automatically generated summaries are available on the merge request page in the **Merge request summaries** dialog, the To-Do list, and in email notifications. + +Provide feedback on this experimental feature in [issue 408991](https://gitlab.com/gitlab-org/gitlab/-/issues/408991). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Draft comment's text + +## Suggested merge or squash commit message **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10453) in GitLab 16.2 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +When preparing to merge your merge request you may wish to edit the squash or merge commit message that will be used. + +To generate a commit message: + +1. Select the **Edit commit message** checkbox on the merge widget. +1. Select **Create AI-generated commit message**. +1. Review the commit message provide and choose **Insert** to add it to the commit. + +Provide feedback on this experimental feature in [issue 408994](https://gitlab.com/gitlab-org/gitlab/-/issues/408994). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Contents of the file +- The filename + +## Generate suggested tests in merge requests **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10366) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). + +This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com that is using Google's Vertex service and the `text-bison` model. It requires the [group-level third-party AI features setting](../../group/manage.md#enable-third-party-ai-features) to be enabled. + +In a merge request, you can get a list of suggested tests for the file you are reviewing. This functionality can help determine if appropriate test coverage has been provided, or if you need more coverage for your project. + +View a [click-through demo](https://go.gitlab.com/Xfp0l4). + +To generate a test suggestion: + +1. In a merge request, select the **Changes** tab. +1. On the header for the file, in the upper-right corner, select **Options** (**{ellipsis_v}**). +1. Select **Suggest test cases**. + +The test suggestion is generated in a sidebar. You can copy the suggestion to your editor and use it as the start of your tests. + +Feedback on this experimental feature can be provided in [issue 408995](https://gitlab.com/gitlab-org/gitlab/-/issues/408995). + +**Data usage**: When you use this feature, the following data is sent to the large language model referenced above: + +- Contents of the file +- The filename diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 4cc8f50dd70..8ca87f4518e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Collaborate on merge requests across forks **(FREE)** +# Collaborate on merge requests across forks **(FREE ALL)** When you open a merge request from your [fork](../repository/forking_workflow.md), you can allow upstream members to collaborate with you on your branch. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 0dcf5f37d65..bace1dfb8b5 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approvals **(FREE)** +# Merge request approvals **(FREE ALL)** You can configure your merge requests so that they must be approved before they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows @@ -87,7 +87,7 @@ GitLab allows all users with Developer or greater [permissions](../../../permiss to approve merge requests. Approvals in GitLab Free are optional, and don't prevent a merge request from merging without approval. -## Required approvals **(PREMIUM)** +## Required approvals **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 169c7a09875..cbbeac17355 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -4,7 +4,7 @@ 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 --- -# Merge request approval rules **(PREMIUM)** +# Merge request approval rules **(PREMIUM ALL)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. They can be used in conjunction @@ -259,7 +259,7 @@ coverage. For more information, see [Coverage check approval rule](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule). -## Security Approvals **(ULTIMATE)** +## Security Approvals **(ULTIMATE ALL)** > - [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. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index eed8cbcd94d..b520ee41493 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -4,7 +4,7 @@ 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 --- -# Merge request approval settings **(PREMIUM)** +# Merge request approval settings **(PREMIUM ALL)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure @@ -63,7 +63,8 @@ this setting, unless you configure one of these options: ## Prevent approvals by users who add commits -> Moved to GitLab Premium in 13.9. +> - 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. 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), @@ -172,5 +173,5 @@ that inherited them. ## Related topics - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) -- [Compliance report](../../../compliance/compliance_report/index.md) +- [Compliance center](../../../compliance/compliance_center/index.md) - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 280ad20712b..75c9083332a 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Merge request workflows **(FREE)** +# Merge request workflows **(FREE ALL)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 79599580f3e..ab882af7eda 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes in merge requests **(FREE)** +# Changes in merge requests **(FREE ALL)** A [merge request](index.md) proposes a set of changes to files in a branch in your repository. These changes are shown as a _diff_ (difference) between the current state and the proposed @@ -16,6 +16,10 @@ to the files in the target branch, and shows only the parts of a file that have  +For technical details on how GitLab calculates the diff between the two revisions, +read [Working with diffs](../../../development/merge_request_concepts/diffs/index.md) +in our development documentation. + ## Show all changes in a merge request To view the diff of changes included in a merge request: @@ -23,9 +27,9 @@ To view the diff of changes included in a merge request: 1. Go to your merge request. 1. Below the merge request title, select **Changes**. 1. If the merge request changes many files, you can jump directly to a specific file: - 1. Select **Show file browser** (**{file-tree}**) to display the file tree. + 1. Select **Show file browser** (**{file-tree}**) or press <kbd>F</kbd> to display the file tree. 1. Select the file you want to view. - 1. To hide the file browser, select **Show file browser** again. + 1. To hide the file browser, select **Show file browser** or press <kbd>F</kbd> again. Files with many changes are collapsed to improve performance. GitLab displays the message: **Some changes are not shown**. To view the changes for that file, select **Expand file**. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 6669b2883a4..d9b2ecf0806 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Cherry-pick changes **(FREE)** +# Cherry-pick changes **(FREE ALL)** In Git, *cherry-picking* is taking a single commit from one branch and adding it as the latest commit on another branch. The rest of the commits in the source branch diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index c930c5c6f7f..1fc7188ffea 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Commit message templates **(FREE)** +# 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. @@ -72,6 +72,7 @@ GitLab creates a squash commit message with this template: > - [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. Commit message templates support these variables: @@ -84,6 +85,7 @@ Commit message templates support these variables: | `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | | `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | | `%{local_reference}` | Local reference to the merge request. | `!72359` | +| `%{source_project_id}` | ID of the merge request's source project. | `123` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | | `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | | `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index a36e45d159a..ddd2a0ddcb5 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge request commits **(FREE)** +# Merge request commits **(FREE ALL)** Each merge request has a history of the commits made to the source branch after the merge request was created. diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index edcc5711b98..901da6d4cf8 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Merge requests for confidential issues **(FREE)** +# Merge requests for confidential issues **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 44cef4d63e5..fefc6aabddf 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge conflicts **(FREE)** +# Merge conflicts **(FREE ALL)** _Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different changes, and you must decide which change to accept. In a merge request, Git compares diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 4eb4476422f..e31460c1997 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "How to create merge requests in GitLab." --- -# Creating merge requests **(FREE)** +# Creating merge requests **(FREE ALL)** GitLab provides many different ways to create a merge request. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f8988ae7bd7..15b2e53d7d9 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,7 +4,7 @@ group: Compliance 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 merge requests to CSV **(FREE)** +# Export merge requests to CSV **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 1cd81e2aac2..b80698f99c3 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request dependencies **(PREMIUM)** +# Merge request dependencies **(PREMIUM ALL)** A single feature can span several merge requests, spread out across multiple projects, and the order in which the work merges can be significant. Use merge request dependencies diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index ff5421d5785..85ebc75e61f 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Draft merge requests **(FREE)** +# Draft merge requests **(FREE ALL)** If a merge request isn't ready to merge, potentially because of continued development or open threads, you can prevent it from being accepted before you diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index dfa62628e46..3ad07d0377e 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge requests **(FREE)** +# Merge requests **(FREE ALL)** To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). @@ -18,10 +18,6 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a quick overview of merge requests, -view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE). - ## Create a merge request Learn the various ways to [create a merge request](creating_merge_requests.md). @@ -168,7 +164,7 @@ a merge request, or: The merge request is added to the user's assigned merge request list. -### Assign multiple users **(PREMIUM)** +### Assign multiple users **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -284,7 +280,7 @@ For a software developer working in a team: 1. You gather feedback from your team. 1. You work on the implementation optimizing code with [Code Quality reports](../../../ci/testing/code_quality.md). 1. You verify your changes with [Unit test reports](../../../ci/testing/unit_test_reports.md) in GitLab CI/CD. -1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). +1. You avoid using dependencies whose license is not compatible with your project with [License approval policies](../../../user/compliance/license_approval_policies.md). 1. You request the [approval](approvals/index.md) from your manager. 1. Your manager: 1. Pushes a commit with their final review. 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 66c3b1fda74..16482d92d7e 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Auto-merge **(FREE)** +# Auto-merge **(FREE ALL)** > **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409530) to **Auto-merge** in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. Enabled by default. @@ -41,6 +41,7 @@ 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. Select **Code > Merge requests**. +1. Select the merge request to edit. 1. Scroll to the merge request reports section. 1. Optional. Select your desired merge options, such as **Delete source branch**, **Squash commits**, or **Edit commit message**. @@ -64,6 +65,7 @@ To do this: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Code > Merge requests**. +1. Select the merge request to edit. 1. Scroll to the merge request reports section. 1. Select **Cancel auto-merge**. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 7bb10303d7e..7eac0e8839a 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge methods **(FREE)** +# Merge methods **(FREE ALL)** The merge method you select for your project determines how the changes in your merge requests are merged into an existing branch. diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index c4288a7793c..14e2ff84eae 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Revert changes **(FREE)** +# Revert changes **(FREE ALL)** You can revert individual commits or an entire merge request in GitLab. When you revert a commit in Git, you create a new commit that reverses all actions diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index f0eb3c015b6..24e3b6a5667 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -1,6 +1,6 @@ --- -stage: ModelOps -group: Applied ML +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 --- diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 54ebfd9eecb..e4882134654 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge request reviews **(FREE)** +# Merge request reviews **(FREE ALL)** [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) @@ -159,7 +159,7 @@ If you have a review in progress, you can also add a comment from the **Overview  -### Approval Rule information for Reviewers **(PREMIUM)** +### Approval Rule information for Reviewers **(PREMIUM ALL)** When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) @@ -225,7 +225,7 @@ To update multiple project merge requests at the same time: 1. Select the appropriate fields and their values from the sidebar. 1. Select **Update all**. -## Bulk edit merge requests at the group level **(PREMIUM)** +## Bulk edit merge requests at the group level **(PREMIUM ALL)** Users with at least the Developer role can manage merge requests. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index f949dba85dd..4857d58933a 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Suggest changes **(FREE)** +# Suggest changes **(FREE ALL)** Reviewers can suggest code changes with a Markdown syntax in merge request diff threads. The merge request author (or other users with the appropriate role) can apply any or diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index b9b8485021b..ea999fe039a 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -4,7 +4,7 @@ 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 --- -# Squash and merge **(FREE)** +# Squash and merge **(FREE ALL)** As you work on a feature branch, you often create small, self-contained commits. These small commits help describe the process of building a feature, but can clutter your Git history after the feature diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index a151a7cbf1b..e0e65c99433 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# External status checks **(ULTIMATE)** +# External status checks **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 120e300da5e..a5635d22530 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -4,7 +4,7 @@ group: Code Review 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 --- -# Merge requests versions **(FREE)** +# Merge requests versions **(FREE ALL)** Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index 639552ca75a..da766b685a3 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge request widgets **(FREE)** +# Merge request widgets **(FREE ALL)** The **Overview** page of a merge request displays status updates from services that perform actions on your merge request. All subscription levels display a @@ -63,13 +63,13 @@ faster to preview proposed modifications. [Read more about Review Apps](../../../ci/review_apps/index.md). -## License compliance **(ULTIMATE)** +## License compliance **(ULTIMATE ALL)** If you have configured [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/index.md) for your project, then you can view a list of licenses that are detected for your project's dependencies.  -## External status checks **(ULTIMATE)** +## External status checks **(ULTIMATE ALL)** If you have configured [external status checks](status_checks.md) you can see the status of these checks in merge requests diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 59b11e78622..7c9a5a37292 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Burndown and burnup charts **(PREMIUM)** +# Burndown and burnup charts **(PREMIUM ALL)** [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 47325ee7c90..4bb751aedc5 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Milestones **(FREE)** +# Milestones **(FREE ALL)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png b/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png Binary files differindex fb4f8d5dc66..8826067f56b 100644 --- a/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png +++ b/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index 4e9e736f067..d4516746afc 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -4,7 +4,7 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# Machine learning model experiments **(FREE)** +# Machine learning model experiments **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 16.2. @@ -71,7 +71,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. Select **Deploy > Model experiments**. +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 7fd5c7cca92..3e78cc5b7f2 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -4,7 +4,7 @@ group: Incubation info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# MLflow client compatibility **(FREE)** +# MLflow client compatibility **(FREE ALL)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. @@ -76,30 +76,30 @@ candidate metadata. To associate a candidate to a CI/CD job: GitLab supports these methods from the MLflow client. Other methods might be supported but were not tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). -| Method | Supported | Version Added | Comments | -|--------------------------|------------------|----------------|----------| -| `get_experiment` | Yes | 15.11 | | -| `get_experiment_by_name` | Yes | 15.11 | | -| `set_experiment` | Yes | 15.11 | | -| `get_run` | Yes | 15.11 | | -| `start_run` | Yes | 15.11 | | -| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_batch` | Yes | 15.11 | | -| `log_metric` | Yes | 15.11 | | -| `log_metrics` | Yes | 15.11 | | -| `log_param` | Yes | 15.11 | | -| `log_params` | Yes | 15.11 | | -| `log_figure` | Yes | 15.11 | | -| `log_image` | Yes | 15.11 | | -| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `set_tag` | Yes | 15.11 | | -| `set_tags` | Yes | 15.11 | | -| `set_terminated` | Yes | 15.11 | | -| `end_run` | Yes | 15.11 | | -| `update_run` | Yes | 15.11 | | -| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. +| Method | Supported | Version Added | Comments | +|--------------------------|------------------|----------------|-------------------------------------------------------------------------------------| +| `get_experiment` | Yes | 15.11 | | +| `get_experiment_by_name` | Yes | 15.11 | | +| `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. | +| `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 | | +| `log_metric` | Yes | 15.11 | | +| `log_metrics` | Yes | 15.11 | | +| `log_param` | Yes | 15.11 | | +| `log_params` | Yes | 15.11 | | +| `log_figure` | Yes | 15.11 | | +| `log_image` | Yes | 15.11 | | +| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. | +| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. | +| `set_tag` | Yes | 15.11 | | +| `set_tags` | Yes | 15.11 | | +| `set_terminated` | Yes | 15.11 | | +| `end_run` | Yes | 15.11 | | +| `update_run` | Yes | 15.11 | | +| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. | ## Limitations diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 85a1dfda679..b280a2645c5 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.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 --- -# Organize work with projects **(FREE)** +# Organize work with projects **(FREE ALL)** In GitLab, you can create projects to host your codebase. You can also use projects to track issues, plan work, diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 5cdf493fe6f..4d8675b104d 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -5,7 +5,7 @@ group: Knowledge 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 Pages DNS records **(FREE)** +# GitLab Pages DNS records **(FREE ALL)** A Domain Name System (DNS) web service routes visitors to websites by translating domain names (such as `www.example.com`) into the 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 0601e236a08..8bf4875ba1e 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 @@ -4,7 +4,7 @@ group: Knowledge 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 Pages custom domains **(FREE)** +# GitLab Pages custom domains **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). @@ -25,6 +25,7 @@ To set up Pages with a custom domain name, read the requirements and steps below ### Prerequisites +- An administrator has configured the server for [GitLab Pages custom domains](../../../../administration/pages/index.md#advanced-configuration) - A GitLab Pages website up and running, served under the default Pages domain (`*.gitlab.io`, for GitLab.com). - A custom domain name `example.com` or subdomain `subdomain.example.com`. @@ -32,17 +33,6 @@ To set up Pages with a custom domain name, read the requirements and steps below - A DNS record (`A`, `ALIAS`, or `CNAME`) pointing your domain to the GitLab Pages server. If there are multiple DNS records on that name, you must use an `ALIAS` record. - A DNS `TXT` record to verify your domain's ownership. -- Set either `external_http` or `external_https` in `/etc/gitlab/gitlab.rb` to the IP and port of - your [Pages daemon](../../../../administration/pages/index.md#the-gitlab-pages-daemon). - If you don't have IPv6, you can omit the IPv6 address. - - Example: - - ```ruby - # Redirect pages from HTTP to HTTPS - gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon - gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # The secondary IPs for the GitLab Pages daemon - ``` ### Steps @@ -301,6 +291,33 @@ To enable this setting: If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). +## Edit a custom domain + +You can edit a custom domain to: + +- View the custom domain. +- View the DNS record to add. +- View the TXT verification entry. +- Retry verification. +- Edit the certificate settings. + +To edit a custom domain: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Deploy > Pages**. +1. Next to the domain name, select **Edit**. + +## Delete a custom domain + +After a custom domain is deleted, the domain is no longer verified in GitLab and cannot be used with GitLab Pages. + +To delete and remove a custom domain: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Deploy > Pages**. +1. Next to the domain name, select **Remove**. +1. When prompted, select **Remove domain**. + ## Troubleshooting ### Domain verification 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 878613c3b9c..5c1fc41d947 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 @@ -6,7 +6,7 @@ group: Knowledge 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 Pages Let's Encrypt certificates **(FREE)** +# GitLab Pages Let's Encrypt certificates **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index 484dc784fdb..f42fdf4fc40 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -5,7 +5,7 @@ group: Knowledge 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 Pages SSL/TLS certificates **(FREE)** +# GitLab Pages SSL/TLS certificates **(FREE ALL)** Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set 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 02e662d15b3..f8ee3f10d1e 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 @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages website from a CI/CD template **(FREE)** +# Create a GitLab Pages website from a CI/CD template **(FREE ALL)** GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). You can create your own `.gitlab-ci.yml` file from one of these templates, and run diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 8332d96d99e..e3b3b99b8e1 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -5,7 +5,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages website from a forked sample project **(FREE)** +# Create a GitLab Pages website from a forked sample project **(FREE ALL)** GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 51f53860fee..545fc6a568b 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -4,7 +4,7 @@ group: Knowledge 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 GitLab Pages website from scratch **(FREE)** +# Tutorial: Create a GitLab Pages website from scratch **(FREE ALL)** This tutorial shows you how to create a Pages site from scratch using the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). You start with diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index ae0dd9507ad..fe073fe6de7 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages website from a project template **(FREE)** +# Create a GitLab Pages website from a project template **(FREE ALL)** GitLab provides templates for the most popular Static Site Generators (SSGs). You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 94dab9dfd17..ab3c12427b3 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Create a GitLab Pages deployment for a static site **(FREE)** +# Create a GitLab Pages deployment for a static site **(FREE ALL)** If you already have a GitLab project that contains your static site or framework, you can generate a GitLab Pages website from it. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 6eb996db210..e44a7bf347f 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -4,7 +4,7 @@ group: Knowledge 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 Pages default domain names and URLs **(FREE)** +# GitLab Pages default domain names and URLs **(FREE ALL)** On this document, learn how to name your project for GitLab Pages according to your intended website's URL. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index e3a32a9afe9..418c97c9433 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -5,7 +5,7 @@ group: Knowledge 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 Pages **(FREE)** +# GitLab Pages **(FREE ALL)** With GitLab Pages, you can publish static websites directly from a repository in GitLab. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index d00af81c10e..4585ee2cecd 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -4,7 +4,7 @@ group: Knowledge 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 Pages settings **(FREE)** +# GitLab Pages settings **(FREE ALL)** This document is a user guide to explore the options and settings GitLab Pages offers. @@ -93,6 +93,7 @@ you can create your project first and access it under `http(s)://namespace.examp > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9347) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `pages_unique_domain`. Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122229) in GitLab 16.3. By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 1b046d03f59..26f28be72ae 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -4,7 +4,7 @@ group: Knowledge 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 Pages access control **(FREE)** +# GitLab Pages access control **(FREE ALL)** You can enable Pages access control on your project if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 68023b87560..8471a4ec55a 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -6,7 +6,7 @@ group: Knowledge 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 Pages public folder **(FREE)** +# GitLab Pages public folder **(FREE ALL)** > With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder). diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index bd8206b3bda..5f1f5bc59ae 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -4,7 +4,7 @@ group: Knowledge 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 Pages redirects **(FREE)** +# GitLab Pages redirects **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 78384249abc..505f1a530cd 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -4,7 +4,7 @@ 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 --- -# Protected branches **(FREE)** +# Protected branches **(FREE ALL)** In GitLab, [permissions](../permissions.md) are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -98,6 +98,7 @@ To protect a branch: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select a role that can merge into this branch. 1. From the **Allowed to push and merge** list, select a role that can push to this branch. @@ -110,7 +111,7 @@ To protect a branch: The protected branch displays in the list of protected branches. -### For all projects in a group **(PREMIUM)** +### For all projects in a group **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default. @@ -135,6 +136,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. In the **Branch** text box, type the branch name or a wildcard. 1. From the **Allowed to merge** list, select a role that can merge into this branch. 1. From the **Allowed to push and merge** list, select a role that can push to this branch. @@ -158,6 +160,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, type the branch name and a wildcard. For example: @@ -200,12 +203,12 @@ To create a new branch through the user interface: ## Require everyone to submit merge requests for a protected branch You can force everyone to submit a merge request, rather than allowing them to -check in directly to a protected branch. This setting is compatible with workflows -like the [GitLab workflow](../../topics/gitlab_flow.md). +check in directly to a protected branch: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. 1. From the **Allowed to push and merge** list, select **No one**. @@ -218,6 +221,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select **Developers + Maintainers**. 1. Select **Protect**. @@ -246,6 +250,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select the deploy key. 1. Select **Protect**. @@ -265,6 +270,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. @@ -277,6 +283,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. Members who can push to this branch can now also force push. @@ -305,7 +312,7 @@ Force push settings for a branch at the project level are overridden by group le if the `group_protected_branches` feature flag is enabled and a group owner has set [group level protection for the same branch](#for-all-projects-in-a-group). -## Require Code Owner approval on a protected branch **(PREMIUM)** +## Require Code Owner approval on a protected branch **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. @@ -318,6 +325,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. Turn on the **Require approval from code owners** toggle. @@ -328,6 +336,7 @@ 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. Select **Settings > Repository**. 1. Expand **Protected branches**. +1. Select **Add protected branch**. 1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. When enabled, all merge requests for these branches require approval diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 0449c9867e2..8686d02271c 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -4,7 +4,7 @@ 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 --- -# Protected tags **(FREE)** +# Protected tags **(FREE ALL)** Protected [tags](repository/tags/index.md): @@ -34,6 +34,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Protected tags**. +1. Select **Add new**. 1. To protect a single tag, select **Tag**, then choose your tag from the dropdown list. 1. To protect all tags with names matching a string: 1. Select **Tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 2dfdb77df9c..d0a938e054d 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -4,7 +4,7 @@ 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 --- -# Push options **(FREE)** +# 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. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 066da445eeb..aee052631fc 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -5,20 +5,13 @@ 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 --- -# GitLab quick actions **(FREE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672) in GitLab 12.1: -> once an action is executed, an alert appears when a quick action is successfully applied. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16877) in GitLab 13.2: you can use -> quick actions when updating the description of issues, epics, and merge requests. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292393) in GitLab 13.8: when you enter -> `/` into a description or comment field, all available quick actions are displayed in a scrollable list. -> - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. +# GitLab quick actions **(FREE ALL)** Quick actions are text-based shortcuts for common actions that are usually done by selecting buttons or dropdowns in the GitLab user interface. You can enter these commands in the descriptions or comments of issues, epics, merge requests, -and commits. +and commits. Quick actions are executed from both new comments and description, and when you edit +existing ones. Many quick actions are context-aware, requiring certain conditions be met. For example, to remove an issue due date with `/remove_due_date`, the issue must have a due date set. @@ -48,90 +41,93 @@ of quotation marks, automatically. The following quick actions are applicable to descriptions, discussions, and threads. Some quick actions might not be available to all subscription tiers. -<!-- Keep this table sorted alphabetically --> -<!-- Don't prettify this table; it will expand out the last field into illegibility --> +<!-- +Keep this table sorted alphabetically + +To auto-format this table, use the VS Code Markdown Table formatter: `https://docs.gitlab.com/ee/development/documentation/styleguide/#editor-extensions-for-table-formatting`. +--> | Command | Issue | Merge request | Epic | Action | |:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| -| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). -| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more active [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. | +| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | +| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | | `/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 created a specific type of to-do item notification. | -| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. -| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given. Copies as much data as possible as long as the target project contains equivalent objects like labels, milestones, or epics. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | | `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Mark issue or epic as confidential. Support for epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213741) in GitLab 15.6. | -| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. -| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. -| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. | | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. -| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. -| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"`. | +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/link` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). | -| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). -| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. -| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. -| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) -| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. -| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | +| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md). | +| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | +| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | | `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. -| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. -| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. -| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. -| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. -| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). -| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. -| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. -| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. -| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. -| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | +| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | +| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | +| `/remove_estimate` or `/remove_time_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. Alias `/remove_time_estimate` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration. | +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic. | +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/severity <severity>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review. | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). | -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3. -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. -| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. -| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. -| `/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. -| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. -| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). -| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). -| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). -| `/unlink <issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove link with to the provided issue. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). +| `/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. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3). | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. | +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | 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. | +| `/unlink <issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove link with to the provided issue. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). | +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid values are integers like `0`, `1`, or `2`. | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). | ## Work items @@ -140,33 +136,39 @@ threads. Some quick actions might not be available to all subscription tiers. Work items in GitLab include [tasks](../tasks.md) and [OKRs](../okrs.md). The following quick actions can be applied through the description field when editing or commenting on work items. -| Command | Task | Objective | Key Result | Action -|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. -| `/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 `¯\＿(ツ)＿/¯`. -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. -| `/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. -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. -| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. -| `/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. -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. -| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. -| `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) and `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. -| `/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. -| `/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. +<!-- +Keep this table sorted alphabetically + +To auto-format this table, use the VS Code Markdown Table formatter: `https://docs.gitlab.com/ee/development/documentation/styleguide/#editor-extensions-for-table-formatting`. +--> + +| Command | Task | Objective | Key Result | Action | +|:--------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| +| `/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. | +| `/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. | +| `/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. | +| `/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`. | +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) or `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current assignees with those specified. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/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 `¯\＿(ツ)＿/¯`. | +| `/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. | +| `/type` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specific assignees. | +| `/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. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | ## Commit messages @@ -176,14 +178,15 @@ The following quick actions are applicable for commit messages: |:----------------------- |:------------------------------------------| | `/tag v1.2.3 <message>` | Tags the commit with an optional message. | -<!-- ## Troubleshooting +## Troubleshooting + +### Quick action isn't executed -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +If you run a quick action, but nothing happens, check if the quick action appears in the autocomplete +box as you type it. +If it doesn't, it's possible that: -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +- The feature related to the quick action isn't available to you based on your subscription tier or + user role in the group or project. +- A required condition for the quick action isn't met. + For example, you're running `/unlabel` on an issue without any labels. diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 40fb6969def..8e65514cd1d 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.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 --- -# Releases **(FREE)** +# Releases **(FREE ALL)** In GitLab, a release enables you to create a snapshot of your project for your users, including installation packages and release notes. You can create a GitLab release on any branch. Creating a @@ -359,7 +359,7 @@ users with at least the Maintainer role to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. -## Release Metrics **(ULTIMATE)** +## Release Metrics **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index c5fb3838b11..e1de9cbdc1c 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -26,7 +26,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \ --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}" ``` -## Install the `release-cli` for the Shell executor **(FREE)** +## Install the `release-cli` for the Shell executor **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. > - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/gitlab-org/release-cli/-/packages). diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md index 990945b1a2b..7f8624fc520 100644 --- a/doc/user/project/releases/release_evidence.md +++ b/doc/user/project/releases/release_evidence.md @@ -4,7 +4,7 @@ group: Compliance 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 --- -# Release evidence **(FREE)** +# Release evidence **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. @@ -91,7 +91,7 @@ When a release is created, release evidence is automatically collected. To initi Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. -## Include report artifacts as release evidence **(ULTIMATE)** +## Include report artifacts as release evidence **(ULTIMATE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index 53c5d342f74..ec3d63462f3 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -4,14 +4,24 @@ 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 **(FREE)** +# Tutorial: Connect a remote machine to the Web IDE (Beta) **(FREE ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. This tutorial shows you how to: - Create a development environment outside of GitLab. - Connect a remote machine to the [Web IDE](../web_ide/index.md). -To connect a remote machine to the Web IDE, you must: +To connect a remote machine to the Web IDE, you'll: 1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). 1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). @@ -102,7 +112,7 @@ Alternatively, you can pass the parameters from a URL and connect directly to th 1. Go to that URL and enter the token you've fetched. -You've done it! Your development environment now runs as a remote host that's connected to the Web IDE. +You've done it! Your development environment now runs as a remote host that's connected to the [Web IDE](../web_ide/index.md). ## Related topics diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index ccb1745d490..16110af984a 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)** +# Remote development (Beta) **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. @@ -16,7 +16,8 @@ On self-managed GitLab, by default this feature is available. To hide the featur WARNING: This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. -You can use remote development to write and compile code hosted on GitLab. With remote development, you can: +You can use remote development to write and compile code hosted on GitLab. +With remote development, you can: - Create a secure development environment in the cloud. - Connect to that environment from your local machine through a web browser or client-based solution. @@ -32,9 +33,10 @@ With remote development, you can use: - The Web IDE as a frontend - A separate machine as a backend runtime environment -For a complete IDE experience, connect the Web IDE to a development environment configured to run as a remote host. You can create this environment [inside](../../workspace/index.md) or [outside](connect_machine.md) of GitLab. +For a complete IDE experience, connect the Web IDE to a development environment configured to run as a remote host. +You can create this environment [inside](../../workspace/configuration.md) or [outside](connect_machine.md) of GitLab. -## Workspace +## Workspaces **(PREMIUM ALL)** A [workspace](../../workspace/index.md) is a virtual sandbox environment for your code in GitLab that includes: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index ae978e2123d..e123debb724 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -5,14 +5,14 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Default branch **(FREE)** +# Default branch **(FREE ALL)** When you create a new [project](../../index.md), GitLab creates a default branch in the repository. A default branch has special configuration options not shared by other branches: - It cannot be deleted. -- It's [initially protected](../../protected_branches.md#protected-branches) against +- It's [initially protected](../../protected_branches.md) against forced pushes. - When a merge request uses an [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically) @@ -94,25 +94,28 @@ Users with the Owner role of groups and subgroups can configure the default bran Projects created in this group after you change the setting use the custom branch name, unless a subgroup configuration overrides it. -## Protect initial default branches **(FREE SELF)** +## Protect initial default branches **(FREE ALL)** > Full protection after initial push [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0. GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md) -to apply to every repository's [default branch](#default-branch) +to apply to every repository's default branch at the [instance level](#instance-level-default-branch-protection) and [group level](#group-level-default-branch-protection) with one of the following options: -- **Not protected** - Both developers and maintainers can push new commits - and force push. +- **Fully protected** - Default value. Developers cannot push new commits, but maintainers can. + No one can force push. +- **Fully protected after initial push** - Developers can push the initial commit + to a repository, but none afterward. Maintainers can always push. No one can force push. - **Protected against pushes** - Developers cannot push new commits, but are allowed to accept merge requests to the branch. Maintainers can push to the branch. - **Partially protected** - Both developers and maintainers can push new commits, but cannot force push. -- **Fully protected** - Developers cannot push new commits, but maintainers can. - No one can force push. -- **Fully protected after initial push** - Developers can push the initial commit - to a repository, but none afterward. Maintainers can always push. No one can force push. +- **Not protected** - Both developers and maintainers can push new commits + and force push. + +WARNING: +Unless **Fully protected** is chosen, a malicious developer could attempt to steal your sensitive data. For example, a malicious `.gitlab-ci.yml` file could be committed to a protected branch and later, if a pipeline is run against that branch, result in exfiltration of group CI/CD variables. ### Instance-level default branch protection **(FREE SELF)** @@ -153,12 +156,12 @@ disable this privilege for group owners, enforcing the instance-level protection NOTE: GitLab administrators can still update the default branch protection of a group. -### Group-level default branch protection **(PREMIUM)** +### Group-level default branch protection **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. > - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. -Instance-level protections for [default branch](#default-branch) +Instance-level protections for the default branch 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 [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 3e9957806c8..f7445ffe950 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -4,7 +4,7 @@ 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" --- -# Branches **(FREE)** +# Branches **(FREE ALL)** Branches are versions of a project's working tree. When you create a new [project](../../index.md), GitLab creates a [default branch](default.md) (which @@ -93,7 +93,7 @@ GitLab provides you multiple methods to protect individual branches. These metho 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. -- Configure [protected branches](../../protected_branches.md#protected-branches) +- Configure [protected branches](../../protected_branches.md) to restrict who can commit to a branch, merge other branches into it, or merge the branch itself into another branch. - Configure [approval rules](../../merge_requests/approvals/rules.md) to set review diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md index 95d5873a535..6f18aabaa46 100644 --- a/doc/user/project/repository/code_suggestions.md +++ b/doc/user/project/repository/code_suggestions.md @@ -1,11 +1,11 @@ --- -stage: ModelOps -group: AI Assisted +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)** +# 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). @@ -26,8 +26,8 @@ Write code more efficiently by using generative AI to suggest code while you're 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 and Microsoft Visual Studio when you have the corresponding GitLab extension installed. -- In the GitLab WebIDE +- 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>. @@ -58,7 +58,9 @@ The best results from Code Suggestions are expected [for languages the Google Ve - Swift - TypeScript - Supported [code infrastructure interfaces](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) include: +### 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) @@ -66,6 +68,47 @@ The best results from Code Suggestions are expected [for languages the Google Ve 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). @@ -150,21 +193,13 @@ on self-managed instances. To request access: After GitLab has provisioned access to Code Suggestions for your instance, the users in your instance can now enable Code Suggestions. -## Enable Code Suggestions in other IDEs and editors - -We have experimental support for Code Suggestions in JetBrains, Neovim, Emacs, Sublime, etc. - -More details in this [blog](https://about.gitlab.com/blog/2023/06/01/extending-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). -- To use VS Code, ensure you have installed [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). -- To use Microsoft Visual Studio, ensure you have installed [the Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). - +- 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: @@ -202,9 +237,11 @@ Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.goo ### 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 diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md index 101878ee4b4..fcf8d538431 100644 --- a/doc/user/project/repository/csv.md +++ b/doc/user/project/repository/csv.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# CSV files **(FREE)** +# CSV files **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14174) in GitLab 14.1. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index dece959bdc9..ee2be6dee7c 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.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 --- -# File finder **(FREE)** +# File finder **(FREE ALL)** With file finder, you can search for a file in a repository directly from the GitLab UI. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index a6bb02989a3..4c37b92b388 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -4,10 +4,10 @@ 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 --- -# Project forking workflow **(FREE)** +# Project forking workflow **(FREE ALL)** Whenever possible, it's recommended to work in a common Git repository and use -[branching strategies](../../../topics/gitlab_flow.md) to manage your work. However, +branching strategies to manage your work. However, if you do not have write access for the repository you want to contribute to, you can create a fork. @@ -134,7 +134,7 @@ an `upstream` remote repository for your fork: git push origin main ``` -### With repository mirroring **(PREMIUM)** +### With repository mirroring **(PREMIUM ALL)** A fork can be configured as a mirror of the upstream if all these conditions are met: @@ -202,7 +202,7 @@ to share objects with another repository: ### Error: `An error occurred while forking the project. Please try again` This error can be due to a mismatch in shared runner settings between the forked project -and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks) +and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#using-shared-runners-in-forked-projects) in the Runner documentation for more information. ### Removing fork relationship fails diff --git a/doc/user/project/repository/geojson.md b/doc/user/project/repository/geojson.md index 723121bc923..eb66a667deb 100644 --- a/doc/user/project/repository/geojson.md +++ b/doc/user/project/repository/geojson.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GeoJSON files **(FREE)** +# GeoJSON files **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14134) in GitLab 16.1. diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 235c1f34d1a..3f49f1e05f2 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file blame." --- -# Git file blame **(FREE)** +# Git file blame **(FREE ALL)** [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index edfcc4b1dc2..db50e6d185e 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file history." --- -# Git file history **(FREE)** +# Git file history **(FREE ALL)** Git file History provides information about the commit history associated with a file. To use it: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 8d8639400bd..8bb6d868270 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -4,7 +4,7 @@ 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)** +# 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. When you add a cryptographic @@ -122,6 +122,7 @@ To add a GPG key to your user settings: 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: diff --git a/doc/user/project/repository/img/contributors_graph.png b/doc/user/project/repository/img/contributors_graph.png Binary files differdeleted file mode 100644 index 83fdf1fc41f..00000000000 --- a/doc/user/project/repository/img/contributors_graph.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 7383772a45b..3d00ceafc05 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -4,7 +4,7 @@ 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 --- -# Repository **(FREE)** +# Repository **(FREE ALL)** A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) is where you store your code and make changes to it. Your changes are tracked with version control. @@ -15,7 +15,7 @@ Each [project](../index.md) contains a repository. To create a repository, you can: -- [Create a project](../../../user/project/index.md#create-a-project) or +- [Create a project](../../../user/project/index.md) or - [Fork an existing project](forking_workflow.md). ## Add files to a repository @@ -237,11 +237,7 @@ Administrators can set a [repository size limit](../../admin_area/settings/accou ## Repository contributor statistics -All code contributors are displayed under your project's **Analyze > Contributor statistics**. - -The graph shows the contributor with the most commits to the fewest. - - +You can view a list and charts of commits made by project members in [Contributor statistics](../../analytics/contributor_statistics.md). ## Repository history graph diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index d3d9b202e63..70ee841a991 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -4,7 +4,7 @@ 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" type: reference --- -# Jupyter Notebook files **(FREE)** +# Jupyter Notebook files **(FREE ALL)** [Jupyter Notebook](https://jupyter.org/) (previously, IPython Notebook) files are used for interactive computing in many fields. They contain a complete record of the diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 550d4535adb..fade9e1b63c 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -4,7 +4,7 @@ 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 --- -# Bidirectional mirroring **(PREMIUM)** +# Bidirectional mirroring **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -138,7 +138,7 @@ This sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update, and Git displays warnings about it. -## Mirror with Perforce Helix with Git Fusion **(PREMIUM)** +## Mirror with Perforce Helix with Git Fusion **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -167,4 +167,5 @@ Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manual ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - [Configure server hooks](../../../../administration/server_hooks.md) diff --git a/doc/user/project/repository/mirror/img/mirror_error_v16_3.png b/doc/user/project/repository/mirror/img/mirror_error_v16_3.png Binary files differnew file mode 100644 index 00000000000..7d3c03534ef --- /dev/null +++ b/doc/user/project/repository/mirror/img/mirror_error_v16_3.png diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 58c6c343282..7ade27e556d 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -4,7 +4,7 @@ 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 --- -# Repository mirroring **(FREE)** +# Repository mirroring **(FREE ALL)** You can _mirror_ a repository to and from external sources. You can select which repository serves as the source. Branches, tags, and commits are synced automatically. @@ -43,6 +43,7 @@ Prerequisites: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. +1. Select **Add new**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original repository is only displayed to users with the Maintainer role or the Owner role for the mirrored project. @@ -76,7 +77,7 @@ non-protected branches in the mirroring project are not mirrored and can diverge To use this option, select **Only mirror protected branches** when you create a repository mirror. -### Mirror specific branches **(PREMIUM)** +### Mirror specific branches **(PREMIUM ALL)** > - Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. @@ -205,193 +206,7 @@ Older versions of SSH may require you to remove `-E md5` from the command. ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Disable mirrors for a project](../../../../administration/settings/visibility_and_access_controls.md#enable-project-mirroring) - [Secrets file and mirroring](../../../../administration/backup_restore/backup_gitlab.md#when-the-secrets-file-is-lost) - -## Troubleshooting - -Should an error occur during a push, GitLab displays an **Error** highlight for that repository. Details on the error can then be seen by hovering over the highlight text. - -### Received RST_STREAM with error code 2 with GitHub - -If you receive this message while mirroring to a GitHub repository: - -```plaintext -13:Received RST_STREAM with error code 2 -``` - -One of these issues might be occurring: - -1. Your GitHub settings might be set to block pushes that expose your email address - used in commits. To fix this problem, either: - - Set your GitHub email address to public. - - Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) - setting. -1. Your repository exceeds GitHub's file size limit of 100 MB. To fix this problem, - check the file size limit configured for on GitHub, and consider using - [Git Large File Storage](https://git-lfs.github.com) to manage large files. - -### Deadline Exceeded - -When upgrading GitLab, a change in how usernames are represented means that you -must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. - -### Connection blocked because server only allows public key authentication - -The connection between GitLab and the remote repository is blocked. Even if a -[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) -is successful, you must check any networking components in the route from GitLab -to the remote server for blockage. - -This error can occur when a firewall performs a `Deep SSH Inspection` on outgoing packets. - -### Could not read username: terminal prompts disabled - -If you receive this error after creating a new project using -[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md): - -- In Bitbucket Cloud: - - ```plaintext - "2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': - terminal prompts disabled\n": exit status 128." - ``` - -- In Bitbucket Server (self-managed): - - ```plaintext - "2:fetch remote: "fatal: could not read Username for 'https://lab.example.com': - terminal prompts disabled\n": exit status 128. - ``` - -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. Select **Settings > Repository**. -1. Expand **Mirroring repositories**. -1. If no repository owner is specified, delete and add the URL again in this format, - replacing `OWNER`, `ACCOUNTNAME`, `PATH_TO_REPO`, and `REPONAME` with your values: - - - In Bitbucket Cloud: - - ```plaintext - https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git - ``` - - - In Bitbucket Server (self-managed): - - ```plaintext - https://OWNER@lab.example.com/PATH_TO_REPO/REPONAME.git - ``` - -When connecting to the Cloud or self-managed Bitbucket repository for mirroring, the repository owner is required in the string. - -### Pull mirror is missing LFS files - -In some cases, pull mirroring does not transfer LFS files. This issue occurs when: - -- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. - An issue exists [to fix this problem for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). -- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. - [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/335123) in GitLab 14.0.6. -- You mirror an external repository using object storage. - An issue exists [to fix this problem](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). - -### `The repository is being updated`, but neither fails nor succeeds visibly - -In rare cases, mirroring slots on Redis can become exhausted, -possibly because Sidekiq workers are reaped due to out-of-memory (OoM) events. -When this occurs, mirroring jobs start and complete quickly, but they neither -fail nor succeed. They also do not leave a clear log. To check for this problem: - -1. Enter the [Rails console](../../../../administration/operations/rails_console.md) - and check Redis' mirroring capacity: - - ```ruby - current = Gitlab::Redis::SharedState.with { |redis| redis.scard('MIRROR_PULL_CAPACITY') }.to_i - maximum = Gitlab::CurrentSettings.mirror_max_capacity - available = maximum - current - ``` - -1. If the mirroring capacity is `0` or very low, you can drain all stuck jobs with: - - ```ruby - Gitlab::Redis::SharedState.with { |redis| redis.smembers('MIRROR_PULL_CAPACITY') }.each do |pid| - Gitlab::Redis::SharedState.with { |redis| redis.srem('MIRROR_PULL_CAPACITY', pid) } - end - ``` - -1. After you run the command, the [background jobs page](../../../../administration/admin_area.md#background-jobs) - should show new mirroring jobs being scheduled, especially when - [triggered manually](#update-a-mirror). - -### Invalid URL - -If you receive this error while setting up mirroring over [SSH](#ssh-authentication), make sure the URL is in a valid format. - -Mirroring does not support the short version of SSH clone URLs (`git@gitlab.com:gitlab-org/gitlab.git`) -and requires the full version including the protocol (`ssh://git@gitlab.com/gitlab-org/gitlab.git`). - -Make sure that host and project path are separated using `/` instead of `:`. - -### Host key verification failed - -This error is returned when the target host public SSH key changes. -Public SSH keys rarely, if ever, change. If host key verification fails, -but you suspect the key is still valid, you can refresh the key's information. - -Prerequisites: - -- You must have at least the Maintainer role for a project. - -To resolve the issue: - -1. [Verify the host key](#verify-a-host-key). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Repository**. -1. Expand **Mirroring repositories**. -1. To refresh the keys, either: - - - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. - - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. - -- Select **Mirror repository**. - -### Transfer mirror users and tokens to a single service account in Rails console - -This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -Use case: If you have multiple users using their own GitHub credentials to set up -repository mirroring, mirroring breaks when people leave the company. Use this -script to migrate disparate mirroring users and tokens into a single service account: - -WARNING: -Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. - -```ruby -svc_user = User.find_by(username: 'ourServiceUser') -token = 'githubAccessToken' - -Project.where(mirror: true).each do |project| - import_url = project.import_url - - # The url we want is https://token@project/path.git - repo_url = if import_url.include?('@') - # Case 1: The url is something like https://23423432@project/path.git - import_url.split('@').last - elsif import_url.include?('//') - # Case 2: The url is something like https://project/path.git - import_url.split('//').last - end - - next unless repo_url - - final_url = "https://#{token}@#{repo_url}" - - project.mirror_user = svc_user - project.import_url = final_url - project.username_only_import_url = final_url - project.save -end -``` diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 56e85157c03..ba54c18f8ee 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -4,7 +4,7 @@ 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 --- -# Pull from a remote repository **(PREMIUM)** +# Pull from a remote repository **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -145,5 +145,6 @@ end ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - [Pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Pull mirroring API](../../../../api/projects.md#configure-pull-mirroring-for-a-project) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 26a60002f0e..cd4fe68b01b 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -4,7 +4,7 @@ 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 --- -# Push mirroring **(FREE)** +# Push mirroring **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. @@ -209,4 +209,5 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me ## Related topics +- [Troubleshooting](troubleshooting.md) for repository mirroring. - [Remote mirrors API](../../../../api/remote_mirrors.md) diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md new file mode 100644 index 00000000000..5817aab5fc7 --- /dev/null +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -0,0 +1,217 @@ +--- +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 +--- + +# Troubleshooting repository mirroring **(FREE ALL)** + +When mirroring fails, project maintainers can see a link similar to **{warning-solid}** **Pull mirroring failed 1 hour ago.** +on the project details page. Select this link to go directly to the mirroring settings, +where GitLab displays an **Error** badge for the mirrored repository. You can hover your mouse cursor +over the badge to display the text of the error: + + + +## Received RST_STREAM with error code 2 with GitHub + +If you receive this message while mirroring to a GitHub repository: + +```plaintext +13:Received RST_STREAM with error code 2 +``` + +One of these issues might be occurring: + +1. Your GitHub settings might be set to block pushes that expose your email address + used in commits. To fix this problem, either: + - Set your GitHub email address to public. + - Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) + setting. +1. Your repository exceeds GitHub's file size limit of 100 MB. To fix this problem, + check the file size limit configured for on GitHub, and consider using + [Git Large File Storage](https://git-lfs.github.com) to manage large files. + +## Deadline Exceeded + +When upgrading GitLab, a change in how usernames are represented means that you +must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. + +## Connection blocked because server only allows public key authentication + +The connection between GitLab and the remote repository is blocked. Even if a +[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) +is successful, you must check any networking components in the route from GitLab +to the remote server for blockage. + +This error can occur when a firewall performs a `Deep SSH Inspection` on outgoing packets. + +## Could not read username: terminal prompts disabled + +If you receive this error after creating a new project using +[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md): + +- In Bitbucket Cloud: + + ```plaintext + "2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': + terminal prompts disabled\n": exit status 128." + ``` + +- In Bitbucket Server (self-managed): + + ```plaintext + "2:fetch remote: "fatal: could not read Username for 'https://lab.example.com': + terminal prompts disabled\n": exit status 128. + ``` + +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. Select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. If no repository owner is specified, delete and add the URL again in this format, + replacing `OWNER`, `ACCOUNTNAME`, `PATH_TO_REPO`, and `REPONAME` with your values: + + - In Bitbucket Cloud: + + ```plaintext + https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git + ``` + + - In Bitbucket Server (self-managed): + + ```plaintext + https://OWNER@lab.example.com/PATH_TO_REPO/REPONAME.git + ``` + +When connecting to the Cloud or self-managed Bitbucket repository for mirroring, the repository owner is required in the string. + +## Pull mirror is missing LFS files + +In some cases, pull mirroring does not transfer LFS files. This issue occurs when: + +- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. + An issue exists [to fix this problem for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). +- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. + [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/335123) in GitLab 14.0.6. +- You mirror an external repository using object storage. + An issue exists [to fix this problem](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). + +## Pull mirroring is not triggering pipelines + +Pipelines might not run for multiple reasons: + +- [Trigger pipelines for mirror updates](pull.md#trigger-pipelines-for-mirror-updates) + might not be enabled. This setting can only be enabled when initially + [configuring pull mirroring](pull.md#configure-pull-mirroring). The status + [is not displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/346630) + when checking the project afterwards. + + When mirroring is set up using [CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/index.md) + this setting is enabled by default. If repository mirroring is manually reconfigured, triggering pipelines + is off by default and this could be why pipelines stop running. +- [`rules`](../../../../ci/yaml/index.md#rules) configuration prevents any jobs from + being added to the pipeline. +- Pipelines are triggered using [the account that set up the pull mirror](https://gitlab.com/gitlab-org/gitlab/-/issues/13697). + If the account is no longer valid, pipelines do not run. +- [Branch protection](../../protected_branches.md#run-pipelines-on-protected-branches) + might prevent the account that set up mirroring from running pipelines. + +## `The repository is being updated`, but neither fails nor succeeds visibly + +In rare cases, mirroring slots on Redis can become exhausted, +possibly because Sidekiq workers are reaped due to out-of-memory (OoM) events. +When this occurs, mirroring jobs start and complete quickly, but they neither +fail nor succeed. They also do not leave a clear log. To check for this problem: + +1. Enter the [Rails console](../../../../administration/operations/rails_console.md) + and check Redis' mirroring capacity: + + ```ruby + current = Gitlab::Redis::SharedState.with { |redis| redis.scard('MIRROR_PULL_CAPACITY') }.to_i + maximum = Gitlab::CurrentSettings.mirror_max_capacity + available = maximum - current + ``` + +1. If the mirroring capacity is `0` or very low, you can drain all stuck jobs with: + + ```ruby + Gitlab::Redis::SharedState.with { |redis| redis.smembers('MIRROR_PULL_CAPACITY') }.each do |pid| + Gitlab::Redis::SharedState.with { |redis| redis.srem('MIRROR_PULL_CAPACITY', pid) } + end + ``` + +1. After you run the command, the [background jobs page](../../../../administration/admin_area.md#background-jobs) + should show new mirroring jobs being scheduled, especially when + [triggered manually](index.md#update-a-mirror). + +## Invalid URL + +If you receive this error while setting up mirroring over [SSH](index.md#ssh-authentication), make sure the URL is in a valid format. + +Mirroring does not support the short version of SSH clone URLs (`git@gitlab.com:gitlab-org/gitlab.git`) +and requires the full version including the protocol (`ssh://git@gitlab.com/gitlab-org/gitlab.git`). + +Make sure that host and project path are separated using `/` instead of `:`. + +## Host key verification failed + +This error is returned when the target host public SSH key changes. +Public SSH keys rarely, if ever, change. If host key verification fails, +but you suspect the key is still valid, you can refresh the key's information. + +Prerequisites: + +- You must have at least the Maintainer role for a project. + +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. Select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. To refresh the keys, either: + + - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. + - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. + +- Select **Mirror repository**. + +## Transfer mirror users and tokens to a single service account in Rails console + +This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +Use case: If you have multiple users using their own GitHub credentials to set up +repository mirroring, mirroring breaks when people leave the company. Use this +script to migrate disparate mirroring users and tokens into a single service account: + +WARNING: +Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. + +```ruby +svc_user = User.find_by(username: 'ourServiceUser') +token = 'githubAccessToken' + +Project.where(mirror: true).each do |project| + import_url = project.import_url + + # The url we want is https://token@project/path.git + repo_url = if import_url.include?('@') + # Case 1: The url is something like https://23423432@project/path.git + import_url.split('@').last + elsif import_url.include?('//') + # Case 2: The url is something like https://project/path.git + import_url.split('//').last + end + + next unless repo_url + + final_url = "https://#{token}@#{repo_url}" + + project.mirror_user = svc_user + project.import_url = final_url + project.username_only_import_url = final_url + project.save +end +``` diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 81896d64815..2756149b5bd 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -4,7 +4,9 @@ group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- -# Push rules **(PREMIUM)** +# Push rules **(PREMIUM ALL)** + +> Maximum regular expression length for push rules [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/411901) from 255 to 511 characters in GitLab 16.3. Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you can enable in a user-friendly interface. Push rules give you more control over what @@ -19,7 +21,7 @@ can and can't be pushed to your repository. While GitLab offers GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules. You can test them at the [regex101 regex tester](https://regex101.com/). -Each regular expression is limited to 255 characters. +Each regular expression is limited to 511 characters. For custom push rules use [server hooks](../../../administration/server_hooks.md). 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 334db91cd82..590323bfadd 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 @@ -4,7 +4,7 @@ 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 --- -# Reduce repository size **(FREE)** +# Reduce repository size **(FREE ALL)** Git repositories become larger over time. When large files are added to a Git repository: diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 85a8917022e..d8d798ac651 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -4,7 +4,7 @@ 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)** +# 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. diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index 8c6774408e6..5a01d6f2085 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -4,7 +4,7 @@ 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 --- -# Tags **(FREE)** +# Tags **(FREE ALL)** In Git, a tag marks an important point in a repository's history. Git supports two types of tags: @@ -97,7 +97,7 @@ To create a tag from the GitLab UI: create a lightweight tag. 1. Select **Create tag**. -## Prevent tag deletion **(PREMIUM)** +## Prevent tag deletion **(PREMIUM ALL)** To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md). diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 2a33476b545..476cfc55298 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,49 +1,11 @@ --- -stage: Create -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 +redirect_to: '../../../editor_extensions/visual_studio_code/index.md' +remove_date: '2023-10-31' --- -# GitLab Workflow extension for VS Code **(FREE)** +This document was moved to [another location](../../../editor_extensions/visual_studio_code/index.md). -The [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) -integrates GitLab with Visual Studio Code. You can decrease context switching and -do more day-to-day tasks in Visual Studio Code, such as: - -- [View issues](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-issues-review-mrs). -- Run [common commands](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#commands) - from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). -- Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) - merge requests directly from Visual Studio Code. -- [Validate your GitLab CI/CD configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-cicd-configuration). -- [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). -- [View the output of CI/CD jobs](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#view-the-job-output). -- [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) - and paste snippets to, and from, your editor. -- [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) - without cloning them. -- [Receive Code Suggestions](code_suggestions.md) - -## Download the extension - -Download the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). - -## Configure the extension - -After you [download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) -you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#extension-settings): - -- [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). -- [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. -- [Code Suggestions](code_suggestions.md) - -## Report issues with the extension - -Report any issues, bugs, or feature requests in the -[`gitlab-vscode-extension` issue queue](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues). - -## Related topics - -- [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) -- [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) -- [View source code](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) +<!-- This redirect file can be deleted after <2023-10-31>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 7b2dcd04982..121a7b41f54 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.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 --- -# Web Editor **(FREE)** +# Web Editor **(FREE ALL)** You can use the Web Editor to make changes to a single file directly from the GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 80538697100..20860718b43 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -4,7 +4,7 @@ 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)** +# Sign commits and tags with X.509 certificates **(FREE ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 4079f821064..1f79982bb1f 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -5,7 +5,7 @@ group: Product Planning 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 --- -# Requirements management **(ULTIMATE)** +# Requirements management **(ULTIMATE ALL)** NOTE: In 14.4, Requirements was moved under **Issues**. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index b508fbcf676..cd09f84641e 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,914 +1,11 @@ --- -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 +redirect_to: 'service_desk/index.md' +remove_date: '2023-10-24' --- -# Service Desk **(FREE)** +This document was moved to [another location](service_desk/index.md). -> Moved to GitLab Free in 13.2. - -With Service Desk, your customers -can email you bug reports, feature requests, or general feedback. -Service Desk provides a unique email address, so they don't need their own GitLab accounts. - -Service Desk emails are created in your GitLab project as new issues. -Your team can respond directly from the project, while customers interact with the thread only -through email. - -## Service Desk workflow - -For example, let's assume you develop a game for iOS or Android. -The codebase is hosted in your GitLab instance, built and deployed -with GitLab CI/CD. - -Here's how Service Desk works for you: - -1. You provide a project-specific email address to your paying customers, who can email you directly - from the application. -1. Each email they send creates an issue in the appropriate project. -1. Your team members go to the Service Desk issue tracker, where they can see new support - requests and respond inside associated issues. -1. Your team communicates with the customer to understand the request. -1. Your team starts working on implementing code to solve your customer's problem. -1. When your team finishes the implementation, the merge request is merged and the issue - is closed automatically. - -Meanwhile: - -- The customer interacts with your team entirely through email, without needing access to your - GitLab instance. -- 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. - -## Troubleshooting Service Desk - -### Emails to Service Desk do not create issues - -Your emails might be ignored because they contain one of the -[email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). +<!-- This redirect file can be deleted after <2023-10-24>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/img/service_desk_confirmation_email.png b/doc/user/project/service_desk/img/service_desk_confirmation_email.png Binary files differindex e08dced1e38..e08dced1e38 100644 --- a/doc/user/project/img/service_desk_confirmation_email.png +++ b/doc/user/project/service_desk/img/service_desk_confirmation_email.png diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/service_desk/img/service_desk_issue_tracker.png Binary files differindex 0fde4c182cf..0fde4c182cf 100644 --- a/doc/user/project/img/service_desk_issue_tracker.png +++ b/doc/user/project/service_desk/img/service_desk_issue_tracker.png diff --git a/doc/user/project/img/service_desk_reply.png b/doc/user/project/service_desk/img/service_desk_reply.png Binary files differindex ae6ce31713b..ae6ce31713b 100644 --- a/doc/user/project/img/service_desk_reply.png +++ b/doc/user/project/service_desk/img/service_desk_reply.png diff --git a/doc/user/project/img/service_desk_thread.png b/doc/user/project/service_desk/img/service_desk_thread.png Binary files differindex 8d8ac39cc5b..8d8ac39cc5b 100644 --- a/doc/user/project/img/service_desk_thread.png +++ b/doc/user/project/service_desk/img/service_desk_thread.png diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md new file mode 100644 index 00000000000..208e798bd21 --- /dev/null +++ b/doc/user/project/service_desk/index.md @@ -0,0 +1,912 @@ +--- +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 +--- + +# Service Desk **(FREE ALL)** + +With Service Desk, your customers +can email you bug reports, feature requests, or general feedback. +Service Desk provides a unique email address, so they don't need their own GitLab accounts. + +Service Desk emails are created in your GitLab project as new issues. +Your team can respond directly from the project, while customers interact with the thread only +through email. + +## Service Desk workflow + +For example, let's assume you develop a game for iOS or Android. +The codebase is hosted in your GitLab instance, built and deployed +with GitLab CI/CD. + +Here's how Service Desk works for you: + +1. You provide a project-specific email address to your paying customers, who can email you directly + from the application. +1. Each email they send creates an issue in the appropriate project. +1. Your team members go to the Service Desk issue tracker, where they can see new support + requests and respond inside associated issues. +1. Your team communicates with the customer to understand the request. +1. Your team starts working on implementing code to solve your customer's problem. +1. When your team finishes the implementation, the merge request is merged and the issue + is closed automatically. + +Meanwhile: + +- The customer interacts with your team entirely through email, without needing access to your + GitLab instance. +- 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. + +## Troubleshooting Service Desk + +### Emails to Service Desk do not create issues + +Your emails might be ignored because they contain one of the +[email headers that GitLab ignores](../../../administration/incoming_email.md#rejected-headers). diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 8330b8c14bc..087330431ad 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -4,7 +4,7 @@ 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" --- -# Migrating projects using file exports **(FREE)** +# Migrating projects using file exports **(FREE ALL)** Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and then imported into another GitLab instance. You can also copy GitLab projects to another location with more automation by @@ -155,14 +155,16 @@ For a quick overview, items that are exported include: - Labels - Milestones - Snippets +- Releases - Time tracking and other project entities - Design management files and data - LFS objects - Issue boards -- Pipelines history +- CI/CD pipelines and pipeline schedules +- Protected branches and tags - Push rules - Emoji reactions -- Group members as long as the user has the Maintainer role in the +- Project and inherited group members, as long as the user has the Maintainer role in the exported project's group or is an administrator ### Items that are not exported @@ -212,7 +214,7 @@ may be possible for an attacker to steal your sensitive data. To import a project: -1. When [creating a new project](../index.md#create-a-project), +1. When [creating a new project](../index.md), select **Import project**. 1. In **Import project from**, select **GitLab export**. 1. Enter your project name and URL. Then select the file you exported previously. diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index c3abfa015a6..79401a7734a 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -187,6 +187,13 @@ e = Projects::ImportExport::ExportService.new(p,u) e.send(:version_saver).send(:save) e.send(:repo_saver).send(:save) +e.send(:avatar_saver).send(:save) +e.send(:project_tree_saver).send(:save) +e.send(:uploads_saver).send(:save) +e.send(:wiki_repo_saver).send(:save) +e.send(:lfs_saver).send(:save) +e.send(:snippets_repo_saver).send(:save) +e.send(:design_repo_saver).send(:save) ## continue using `e.send(:exporter_name).send(:save)` going through the list of exporters # The following line should show you the export_path similar to /var/opt/gitlab/gitlab-rails/shared/tmp/gitlab_exports/@hashed/49/94/4994.... diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 4a7e7d2fe7d..6c2140595d9 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -5,7 +5,7 @@ info: 'To determine the technical writer assigned to the Stage/Group associated type: reference, index, howto --- -# Project settings **(FREE)** +# Project settings **(FREE ALL)** Use the **Settings** page to manage the configuration options in your [project](../index.md). @@ -46,7 +46,7 @@ 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)** +## Add a compliance framework to a project **(PREMIUM ALL)** You can [add compliance frameworks to projects](../../group/compliance_frameworks.md#add-a-compliance-framework-to-a-project) @@ -74,7 +74,7 @@ Use the toggles to enable or disable features in the project. | **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#git-large-file-storage-lfs). +| **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. @@ -161,7 +161,7 @@ Prerequisites: 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#description-templates). +- 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). @@ -175,7 +175,7 @@ Configure your project's merge request settings: ## Service Desk -Enable [Service Desk](../service_desk.md) for your project to offer customer support. +Enable [Service Desk](../service_desk/index.md) for your project to offer customer support. ## Export project @@ -312,7 +312,7 @@ To delete a project: This action deletes the project and all associated resources (such as issues and merge requests). -### Delayed project deletion **(PREMIUM)** +### Delayed project deletion **(PREMIUM ALL)** > - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. > - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. @@ -346,7 +346,7 @@ To immediately delete a project marked for deletion: 1. In the **Delete this project** section, select **Delete project**. 1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -## Restore a project **(PREMIUM)** +## Restore a project **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. @@ -381,7 +381,7 @@ Automatically [create](../../../operations/incident_management/alerts.md#trigger Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). -### Status Page **(ULTIMATE)** +### Status Page **(ULTIMATE ALL)** [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). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index f4652d592f0..78620eb2ab3 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -81,6 +81,9 @@ To revoke a project access token: The scope determines the actions you can perform when you authenticate with a project access token. +NOTE: +See the warning in [create a project access token](#create-a-project-access-token) regarding internal projects. + | Scope | Description | |:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 56873c328fa..84ff9efbd14 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -4,7 +4,7 @@ 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 --- -# System notes **(FREE)** +# System notes **(FREE ALL)** System notes are short descriptions that help you understand the history of events that occur during the life cycle of a GitLab object, such as: diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 9b5469f6cec..ec8d886c68e 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Time tracking **(FREE)** +# Time tracking **(FREE ALL)** You can estimate and track the time you spend on [issues](issues/index.md) and [merge requests](merge_requests/index.md). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 45abcd867c0..994ed244832 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/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 --- -# Web IDE **(FREE)** +# Web IDE **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [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. @@ -217,3 +217,16 @@ You cannot use interactive web terminals to interact with a runner. However, you can use a terminal to install dependencies and compile and debug code. For more information about configuring a workspace that supports interactive web terminals, see [remote development](../remote_development/index.md). + +## Troubleshooting + +When working with the Web IDE, you might encounter the following issues. + +### Character offset in the Web IDE + +When you type in the Web IDE, you might get a four-character offset. To resolve the issue, do one of the following: + +- Add `"editor.disableMonospaceOptimizations": true` to your settings. +- Modify your `"editor.font"` setting. + +For more information, see [VS Code issue 80170](https://github.com/microsoft/vscode/issues/80170). diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 41fd7e81db5..916c8abf066 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Group wikis **(PREMIUM)** +# Group wikis **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in GitLab 13.5. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 4a53faeee73..71fc4dd20a3 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -4,7 +4,7 @@ group: Knowledge 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 --- -# Wiki **(FREE)** +# Wiki **(FREE ALL)** > - Page loading [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/336792) to asynchronous in GitLab 14.9. > - Page slug encoding method [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71753) to `ERB::Util.url_encode` in GitLab 14.9. @@ -287,7 +287,7 @@ 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. Select **Settings > Integrations**. 1. Select **External wiki**. -1. In the **Enable integration** section, clear the **Active** checkbox. +1. Under **Enable integration**, clear the **Active** checkbox. 1. Select **Save changes**. ## Disable the project's wiki diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 472bbb81648..8c050caed17 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.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" --- -# Manage projects **(FREE)** +# Manage projects **(FREE ALL)** Most work in GitLab is done in a [project](../../user/project/index.md). Files and code are saved in projects, and most features are in the scope of projects. @@ -151,7 +151,7 @@ To delete a project: 1. Select **Delete project**. 1. Confirm this action by completing the field. -## View projects pending deletion **(PREMIUM)** +## View projects pending deletion **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. > - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. @@ -178,7 +178,15 @@ To view the activity of a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Manage > Activity**. -1. Select a tab to view the type of project activity. +1. Optional. To filter activity by contribution type, select a tab: + + - **All**: All contributions by project members. + - **Push events**: Push events in the project. + - **Merge events**: Accepted merge requests in the project. + - **Issue events**: Issues opened and closed in the project. + - **Comments**: Comments posted by project members. + - **Designs**: Designs added, updated, and removed in the project. + - **Team**: Members who joined and left the project. ## Search in projects diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 57439a4595e..5f43f177e36 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Project and group visibility **(FREE)** +# Project and group visibility **(FREE ALL)** Projects and groups in GitLab can be private, internal, or public. diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 23a662ccfeb..bad62825ba5 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -4,7 +4,7 @@ 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 --- -# Report abuse **(FREE)** +# Report abuse **(FREE ALL)** You can report abuse from other GitLab users to GitLab administrators. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index bc9de9357f6..75eed6d4b52 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.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 --- -# Reserved project and group names **(FREE)** +# Reserved project and group names **(FREE ALL)** Not all project & group names are allowed because they would conflict with existing routes used by GitLab. diff --git a/doc/user/rich_text_editor.md b/doc/user/rich_text_editor.md index ea85dfdbcb4..c60c89eb0de 100644 --- a/doc/user/rich_text_editor.md +++ b/doc/user/rich_text_editor.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Rich text editor **(FREE)** +# Rich text editor **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) for [wikis](project/wiki/index.md#rich-text-editor) in GitLab 14.0. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371931) for editing issue descriptions in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 5a9f75f1d6c..c12d7889fb8 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced search **(PREMIUM)** +# Advanced search **(PREMIUM ALL)** > Moved to GitLab Premium in 13.9. @@ -87,13 +87,17 @@ In user search, a [fuzzy query](https://www.elastic.co/guide/en/elasticsearch/re ## Known issues - 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. + 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: ```plaintext . , : ; / ` ' = ? $ & ^ | < > ( ) { } [ ] @ ``` + For more information, see [issue 325234](https://gitlab.com/gitlab-org/gitlab/-/issues/325234). - Search results show only the first match in a file. + For more information, see [issue 668](https://gitlab.com/gitlab-org/gitlab/-/issues/668). diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md index ab284bd6a5f..671afe13ace 100644 --- a/doc/user/search/command_palette.md +++ b/doc/user/search/command_palette.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Command palette **(FREE)** +# Command palette **(FREE ALL)** > Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default. diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md index 469d91b5194..8a64dc9e70f 100644 --- a/doc/user/search/exact_code_search.md +++ b/doc/user/search/exact_code_search.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Exact Code Search **(PREMIUM)** +# Exact Code Search **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `index_code_with_zoekt` for indexing and `search_code_with_zoekt` for searching. Both are disabled by default. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index fe5ee3a5e0a..5600f18c61c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -4,7 +4,7 @@ group: Global Search 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 --- -# Searching in GitLab **(FREE)** +# Searching in GitLab **(FREE ALL)** GitLab has two types of searches available: **basic** and **advanced**. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index ac3c6bace09..d8b4d147d24 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab keyboard shortcuts **(FREE)** +# GitLab keyboard shortcuts **(FREE ALL)** GitLab has several keyboard shortcuts you can use to access its different features. @@ -92,17 +92,18 @@ relatively quickly to work, and they take you to another page in the project. These shortcuts are available when viewing issues: -| Keyboard shortcut | Description | -|------------------------------|-------------| -| <kbd>e</kbd> | Edit description. | -| <kbd>a</kbd> | Change assignee. | -| <kbd>m</kbd> | Change milestone. | -| <kbd>l</kbd> | Change label. | -| <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>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | -| <kbd>→</kbd> | Go to the next design. | -| <kbd>←</kbd> | Go to the previous design. | -| <kbd>Escape</kbd> | Close the design. | +| Keyboard shortcut | Description | +|-------------------------------|-------------| +| <kbd>e</kbd> | Edit description. | +| <kbd>a</kbd> | Change assignee. | +| <kbd>m</kbd> | Change milestone. | +| <kbd>l</kbd> | Change label. | +| <kbd>c</kbd> + <kbd>r</kbd> | Copy issue 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>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | +| <kbd>→</kbd> | Go to the next design. | +| <kbd>←</kbd> | Go to the previous design. | +| <kbd>Escape</kbd> | Close the design. | ### Merge requests @@ -116,6 +117,7 @@ These shortcuts are available when viewing [merge requests](project/merge_reques | <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. | @@ -230,6 +232,14 @@ page (go to **Code > Repository graph**): | <kbd>Shift</kbd> + <kbd>↑</kbd> or <kbd>Shift</kbd> + <kbd>k</kbd> | Scroll to top. | | <kbd>Shift</kbd> + <kbd>↓</kbd> or <kbd>Shift</kbd> + <kbd>j</kbd> | Scroll to bottom. | +### Incidents + +These shortcuts are available when viewing incidents: + +| Keyboard shortcut | Description | +|-------------------------------|-------------| +| <kbd>c</kbd> + <kbd>r</kbd> | Copy incident reference. | + ### Wiki pages This shortcut is available when viewing a [wiki page](project/wiki/index.md): @@ -301,15 +311,16 @@ These shortcuts are available when using a [filtered search input](search/index. | <kbd>Command</kbd> | <kbd>Delete</kbd> | Clear entire search filter. | | <kbd>Option</kbd> | <kbd>Control</kbd> + <kbd>Delete</kbd> | Clear one token at a time. | -## Epics **(PREMIUM)** +## Epics **(PREMIUM ALL)** These shortcuts are available when viewing [epics](group/epics/index.md): -| Keyboard shortcut | Description | -|-------------------|-------------------| -| <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>e</kbd> | Edit description. | -| <kbd>l</kbd> | Change label. | +| Keyboard shortcut | Description | +|------------------------------|-------------------| +| <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>e</kbd> | Edit description. | +| <kbd>l</kbd> | Change label. | +| <kbd>c</kbd> + <kbd>r</kbd> | Copy epic reference. | ## Disable keyboard shortcuts diff --git a/doc/user/snippets.md b/doc/user/snippets.md index aace26b4bb0..a5a547727d3 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Snippets **(FREE)** +# Snippets **(FREE ALL)** With GitLab snippets, you can store and share bits of code and text with other users. You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and @@ -247,8 +247,8 @@ GitLab forwards the spam to Akismet. than 10 files results in an error. - Revisions are not visible to the user on the GitLab UI, but [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) for updates. -- The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) - is 50 MB, by default. +- The default [maximum size for a snippet](../administration/snippets/index.md) + is 50 MB. - Git LFS is not supported. ### Reduce snippets repository size diff --git a/doc/user/ssh.md b/doc/user/ssh.md index d92e3944521..f418cc5f6b7 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -4,7 +4,7 @@ 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 --- -# Use SSH keys to communicate with GitLab **(FREE)** +# Use SSH keys to communicate with GitLab **(FREE ALL)** Git is a distributed version control system, which means you can work locally, then share or *push* your changes to a server. In this case, the server you push to is GitLab. @@ -20,7 +20,7 @@ SSH uses two keys, a public key and a private key. - The public key can be distributed. - The private key should be protected. -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. +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), which makes your use of GitLab and your data even more secure. @@ -325,6 +325,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. +1. Select **Add new key**. 1. In the **Key** box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, which starts with `ssh-rsa`, `ssh-dss`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md new file mode 100644 index 00000000000..210aca4ee35 --- /dev/null +++ b/doc/user/storage_management_automation.md @@ -0,0 +1,1145 @@ +--- +type: howto +stage: Fulfillment +group: Utilization +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 +--- + +# Storage management automation **(FREE ALL)** + +You can manage your storage through the GitLab UI and the API. This page describes how to +automate storage analysis and cleanup to manage your [usage quota](usage_quotas.md). You can also +manage your storage usage by making your pipelines more efficient. For more information, see [pipeline efficiency](../ci/pipelines/pipeline_efficiency.md). + +You can also use the [GitLab community forum and Discord](https://about.gitlab.com/community/) to ask for help with API automation. + +## API requirements + +To automate storage management, your GitLab.com SaaS or self-managed instance must have access to the [GitLab REST API](../api/api_resources.md). + +### API authentication scope + +You must use the following scopes to [authenticate](../api/rest/index.md#authentication) with the API: + +- Storage analysis: + - Read API access with the `read_api` scope. + - At least the Developer role on all projects. +- Storage clean up: + - 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. + +### Command line + +You must install the following tools to send API requests: + +- Install `curl` with your preferred package manager. +- Install the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) and use the `api` subcommand. +- Install `jq` to format JSON responses. For more information, see [Tips for productive DevOps workflows: JSON formatting with jq and CI/CD linting automation](https://about.gitlab.com/blog/2021/04/21/devops-workflows-json-format-jq-ci-cd-lint/). + +Example with `curl` and `jq`: + +```shell +export GITLAB_TOKEN=xxx + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/user" | jq +``` + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +glab auth login + +glab api groups/YOURGROUPNAME/projects +``` + +#### Using the GitLab CLI + +Some API endpoints require [pagination](../api/rest/index.md#pagination) and subsequent page fetches to retrieve all results. The [GitLab CLI](../editor_extensions/gitlab_cli/index.md) provides the flag `--paginate`. + +Requests that require sending a POST body formatted as JSON data can be written as `key=value` pairs passed to the `--raw-field` parameter. + +For more information, see the [GitLab CLI endpoint documentation](../editor_extensions/gitlab_cli/index.md#core-commands). + +### API client libraries + +The storage management and cleanup automation methods described in this page use the [`python-gitlab`](https://python-gitlab.readthedocs.io/en/stable/) library in programmatic example. The `python-gitlab` library provides +a feature-rich programming interface. For more information about use cases for the `python-gitlab` library, +see [Efficient DevSecOps workflows: Hands-on `python-gitlab` API automation](https://about.gitlab.com/blog/2023/02/01/efficient-devsecops-workflows-hands-on-python-gitlab-api-automation/). + +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. + +## Strategies for storage analysis + +### Identify the storage types + +The [projects API endpoint](../api/projects.md#list-all-projects) provides statistics for projects +in your GitLab instance. To use the projects API endpoint, set the `statistics` key to boolean `true`. +This data provides insight into storage consumption of the project by the following storage types: + +- `storage_size`: Overall storage +- `lfs_objects_size`: LFS objects storage +- `job_artifacts_size`: Job artifacts storage +- `packages_size`: Packages storage +- `repository_size`: Git repository storage +- `snippets_size`: Snippets storage +- `uploads_size`: Uploads storage +- `wiki_size`: Wiki storage + +Additional queries are required for detailed storage statistics for [job artifacts](../api/job_artifacts.md), the [container registry](../api/container_registry.md), the [package registry](../api/packages.md) and [dependency proxy](../api/dependency_proxy.md). It is explained later in this how-to. + +Example that uses `curl` and `jq` on the command line: + +```shell +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID?statistics=true" | jq --compact-output '.id,.statistics' | jq +48349590 +{ + "commit_count": 2, + "storage_size": 90241770, + "repository_size": 3521, + "wiki_size": 0, + "lfs_objects_size": 0, + "job_artifacts_size": 90238249, + "pipeline_artifacts_size": 0, + "packages_size": 0, + "snippets_size": 0, + "uploads_size": 0 +} +``` + +Example that uses the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +export GL_PROJECT_ID=48349590 +glab api --method GET projects/$GL_PROJECT_ID --field 'statistics=true' | jq --compact-output '.id,.statistics' | jq +48349590 +{ + "commit_count": 2, + "storage_size": 90241770, + "repository_size": 3521, + "wiki_size": 0, + "lfs_objects_size": 0, + "job_artifacts_size": 90238249, + "pipeline_artifacts_size": 0, + "packages_size": 0, + "snippets_size": 0, + "uploads_size": 0 +} +``` + +Example using the `python-gitlab` library: + +```python +project_obj = gl.projects.get(project.id, statistics=True) + +print("Project {n} statistics: {s}".format(n=project_obj.name_with_namespace, s=json.dump(project_obj.statistics, indent=4))) +``` + +You can find an example implementation in the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` which is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). Export the `GL_GROUP_ID` environment variable and run the script to see the project statistics printed in the terminal. + +```shell +export GL_TOKEN=xxx +export GL_GROUP_ID=56595735 + +pip3 install python-gitlab +python3 get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py + +Project Developer Evangelism and Technical Marketing at GitLab / playground / Artifact generator group / Gen Job Artifacts 4 statistics: { + "commit_count": 2, + "storage_size": 90241770, + "repository_size": 3521, + "wiki_size": 0, + "lfs_objects_size": 0, + "job_artifacts_size": 90238249, + "pipeline_artifacts_size": 0, + "packages_size": 0, + "snippets_size": 0, + "uploads_size": 0 +} +``` + +### Analyzing multiple subgroups and projects + +You can use automation to analyze multiple projects and groups. For example, you can start at the top namespace level, +and recursively analyze all subgroups and projects. You can also analyze different storage types. + +Here's an example of an algorithm that analyzes multiple subgroups and projects: + +1. Fetch the top-level namespace ID. You can copy the ID value from the [namespace/group overview](../user/namespace/index.md#types-of-namespaces). +1. Fetch all [subgroups](../api/groups.md#list-a-groups-subgroups) from the top-level group, and save the IDs in a list. +1. Loop over all groups and fetch all [projects from each group](../api/groups.md#list-a-groups-projects) and save the IDs in a list. +1. Identify the storage type to analyze, and collect the information from project attributes, like project statistics, and job artifacts. +1. Print an overview of all projects, grouped by group, and their storage information. + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +export GROUP_NAME="gitlab-de" + +# Return sub group IDs +glab api groups/$GROUP_NAME/subgroups | jq --compact-output '.[]' | jq --compact-output '.id' +12034712 +67218622 +67162711 +67640130 +16058698 +12034604 + +# Loop over all subgroups to get subgroups, until the result set is empty. Example group: 12034712 +glab api groups/12034712/subgroups | jq --compact-output '.[]' | jq --compact-output '.id' +56595735 +70677315 +67218606 +70812167 + +# Lowest group level +glab api groups/56595735/subgroups | jq --compact-output '.[]' | jq --compact-output '.id' +# empty result, return and continue with analysis + +# Fetch projects from all collected groups. Example group: 56595735 +glab api groups/56595735/projects | jq --compact-output '.[]' | jq --compact-output '.id' +48349590 +48349263 +38520467 +38520405 + +# Fetch storage types from a project (ID 48349590): Job artifacts in the `artifacts` key +glab api projects/48349590/jobs | jq --compact-output '.[]' | jq --compact-output '.id, .artifacts' +4828297946 +[{"file_type":"archive","size":52444993,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":156,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3140,"filename":"job.log","file_format":null}] +4828297945 +[{"file_type":"archive","size":20978113,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3147,"filename":"job.log","file_format":null}] +4828297944 +[{"file_type":"archive","size":10489153,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":158,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3146,"filename":"job.log","file_format":null}] +4828297943 +[{"file_type":"archive","size":5244673,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3145,"filename":"job.log","file_format":null}] +4828297940 +[{"file_type":"archive","size":1049089,"filename":"artifacts.zip","file_format":"zip"},{"file_type":"metadata","size":157,"filename":"metadata.gz","file_format":"gzip"},{"file_type":"trace","size":3140,"filename":"job.log","file_format":null}] +``` + +While the shell approach with `glab` works for smaller analysis, you should consider a script that +uses the API client libraries. This improves readability, storing data, flow control, testing, and reusability. + +You can also implement this algorithm with a Python script that uses the `python-gitlab` library: + +```python +#!/usr/bin/env python + +import datetime +import gitlab +import os +import sys + +GITLAB_SERVER = os.environ.get('GL_SERVER', 'https://gitlab.com') +GITLAB_TOKEN = os.environ.get('GL_TOKEN') # token requires developer permissions +PROJECT_ID = os.environ.get('GL_PROJECT_ID') #optional +GROUP_ID = os.environ.get('GL_GROUP_ID') #optional + +if __name__ == "__main__": + if not GITLAB_TOKEN: + print("🤔 Please set the GL_TOKEN env variable.") + sys.exit(1) + + gl = gitlab.Gitlab(GITLAB_SERVER, private_token=GITLAB_TOKEN, pagination="keyset", order_by="id", per_page=100) + + # Collect all projects, or prefer projects from a group id, or a project id + projects = [] + + # Direct project ID + if PROJECT_ID: + projects.append(gl.projects.get(PROJECT_ID)) + # Groups and projects inside + elif GROUP_ID: + group = gl.groups.get(GROUP_ID) + + for project in group.projects.list(include_subgroups=True, get_all=True): + manageable_project = gl.projects.get(project.id , lazy=True) + projects.append(manageable_project) + + for project in projects: + jobs = project.jobs.list(pagination="keyset", order_by="id", per_page=100, iterator=True) + for job in jobs: + print("DEBUG: ID {i}: {a}".format(i=job.id, a=job.attributes['artifacts'])) +``` + +The script outputs the project job artifacts in a JSON formatted list: + +```json +[ + { + "file_type": "archive", + "size": 1049089, + "filename": "artifacts.zip", + "file_format": "zip" + }, + { + "file_type": "metadata", + "size": 157, + "filename": "metadata.gz", + "file_format": "gzip" + }, + { + "file_type": "trace", + "size": 3146, + "filename": "job.log", + "file_format": null + } +] +``` + +The full script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` with specific examples for automating storage management and cleanup is located is located in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. To ensure the script doesn't reach [API rate limits](../api/rest/index.md#rate-limits), the example code is not optimized for parallel API requests. + +### Helper functions + +You may need to convert timestamp seconds into a duration format, or print raw bytes in a more +representative format. You can use the following helper functions to transform values for improved +readability: + +```shell +# Current Unix timestamp +date +%s + +# Convert `created_at` date time with timezone to Unix timestamp +date -d '2023-08-08T18:59:47.581Z' +%s +``` + +Example with Python that uses the `python-gitlab` API library: + +```python +def render_size_mb(v): + return "%.4f" % (v / 1024 / 1024) + +def render_age_time(v): + return str(datetime.timedelta(seconds = v)) + +# Convert `created_at` date time with timezone to Unix timestamp +def calculate_age(created_at_datetime): + created_at_ts = datetime.datetime.strptime(created_at_datetime, '%Y-%m-%dT%H:%M:%S.%fZ') + now = datetime.datetime.now() + return (now - created_at_ts).total_seconds() +``` + +## Managing storage in CI/CD pipelines + +WARNING: +Deleting job log and artifacts is a destructive action that cannot be reverted. Use with caution. Deleting certain files, including report artifacts, job logs, and metadata files, affects GitLab features that use these files as data sources. + +Job artifacts consume most of the pipeline storage, and job logs can also generate several hundreds of kilobytes. +You should delete the unnecessary job artifacts first and then clean up job logs after analysis. + +### Analyze pipeline storage + +The following example shows a response from a query for job artifacts in a project: + +```json +[ + { + "file_type": "archive", + "size": 1049089, + "filename": "artifacts.zip", + "file_format": "zip" + }, + { + "file_type": "metadata", + "size": 157, + "filename": "metadata.gz", + "file_format": "gzip" + }, + { + "file_type": "trace", + "size": 3146, + "filename": "job.log", + "file_format": null + } +] +``` + +The [Job API endpoint](../api/jobs.md#list-project-jobs) returns the job artifacts `file_type` key in the `artifacts` attribute. The the job artifacts `file_type` key provides insights into the specific artifact type: + +- `archive` is used for the generated job artifacts as a zip file. +- `metadata` is used for additional metadata in a Gzip file. +- `trace` is used for the `job.log` as a raw file. + +These three types are relevant for storage counting, and should be collected for a later summary. Based on the example code for fetching all projects, you can extend the Python script to do more analysis. + +The Python code loops over all projects, and fetches a `project_obj` object variable that contains all attributes. Because there can be many pipelines and jobs, fetching the list of jobs can be expensive in one call. Therefore, this is done using [keyset pagination](https://python-gitlab.readthedocs.io/en/stable/api-usage.html#pagination). The remaining step is to fetch the `artifacts` attribute from the `job` object. + +Based on how you implement the script, you could either: + +- Collect all job artifacts and print a summary table at the end of the script. +- Print the information immediately. + +Collecting the job artifacts provides a data structure that can be written as a cache file to +disk for example, which you can use when testing the implementation. + +In the following example, the job artifacts are collected in the `ci_job_artifacts` list. + +```python + ci_job_artifacts = [] + + for project in projects: + project_obj = gl.projects.get(project.id) + + jobs = project.jobs.list(pagination="keyset", order_by="id", per_page=100, iterator=True) + + for job in jobs: + artifacts = job.attributes['artifacts'] + #print("DEBUG: ID {i}: {a}".format(i=job.id, a=json.dumps(artifacts, indent=4))) + if not artifacts: + continue + + for a in artifacts: + data = { + "project_id": project_obj.id, + "project_web_url": project_obj.name, + "project_path_with_namespace": project_obj.path_with_namespace, + "job_id": job.id, + "artifact_filename": a['filename'], + "artifact_file_type": a['file_type'], + "artifact_size": a['size'] + } + + ci_job_artifacts.append(data) + + print("\nDone collecting data.") + + if len(ci_job_artifacts) > 0: + print("|Project|Job|Artifact name|Artifact type|Artifact size|\n|-|-|-|-|-|") #Start markdown friendly table + for artifact in ci_job_artifacts: + print('| [{project_name}]({project_web_url}) | {job_name} | {artifact_name} | {artifact_type} | {artifact_size} |'.format(project_name=artifact['project_path_with_namespace'], project_web_url=artifact['project_web_url'], job_name=artifact['job_id'], artifact_name=artifact['artifact_filename'], artifact_type=artifact['artifact_file_type'], artifact_size=render_size_mb(artifact['artifact_size']))) + else: + print("No artifacts found.") +``` + +At the end of the script, the job artifacts are printed as a Markdown formatted table. You can copy the table content into a new issue comment or description, or populate a Markdown file in a GitLab repository. + +```shell +$ python3 get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py + +|Project|Job|Artifact name|Artifact type|Artifact size| +|-|-|-|-|-| +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297946 | artifacts.zip | archive | 50.0154 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297946 | metadata.gz | metadata | 0.0001 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297946 | job.log | trace | 0.0030 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297945 | artifacts.zip | archive | 20.0063 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297945 | metadata.gz | metadata | 0.0001 | +| [gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4](Gen Job Artifacts 4) | 4828297945 | job.log | trace | 0.0030 | +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). To ensure the script doesn't hit [API rate limits](../api/rest/index.md#rate-limits), the example code is not optimized for parallel API requests. + +### Delete job artifacts + +You can use a filter to select the types of job artifacts to delete in bulk. A typical request: + +- Deletes job artifacts older than the specified number of days. +- Deletes job artifacts that exceed a specified amount of storage. For example, 100 MB. + +You can use a Python script to implement this type of filter. You can filter the API queries results, and compare +the `created_at` value to calculate the artifact age. + +You can also loop over all job artifacts and compare their `size` attribute to see whether they match +the size threshold. When a matching job has been found, it is marked for deletion. Because of the +analysis that happens when the script loops through job attributes, the job can be marked as deleted +only. When the collection loops remove the object locks, all marked as deleted jobs can actually be deleted. + +```python + for project in projects: + project_obj = gl.projects.get(project.id) + + jobs = project.jobs.list(pagination="keyset", order_by="id", per_page=100, iterator=True) + + for job in jobs: + artifacts = job.attributes['artifacts'] + if not artifacts: + continue + + # Advanced filtering: Age and Size + # Example: 90 days, 10 MB threshold (TODO: Make this configurable) + threshold_age = 90 * 24 * 60 * 60 + threshold_size = 10 * 1024 * 1024 + + # job age, need to parse API format: 2023-08-08T22:41:08.270Z + created_at = datetime.datetime.strptime(job.created_at, '%Y-%m-%dT%H:%M:%S.%fZ') + now = datetime.datetime.now() + age = (now - created_at).total_seconds() + # Shorter: Use a function + # age = calculate_age(job.created_at) + + for a in artifacts: + # ... removed analysis collection code for readability + + # Advanced filtering: match job artifacts age and size against thresholds + if (float(age) > float(threshold_age)) or (float(a['size']) > float(threshold_size)): + # mark job for deletion (cannot delete inside the loop) + jobs_marked_delete_artifacts.append(job) + + print("\nDone collecting data.") + + # Advanced filtering: Delete all job artifacts marked to being deleted. + for job in jobs_marked_delete_artifacts: + # delete the artifact + print("DEBUG", job) + job.delete_artifacts() + + # Print collection summary (removed for readability) +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +#### Delete all job artifacts for a project + +If you do not need the project's [job artifacts](../ci/jobs/job_artifacts.md), you can +use the following command to delete them all. This action cannot be reverted. + +Job artifact deletion happens asynchronously in GitLab and can take a while to complete in the background. Subsequent analysis queries against the API can still return the artifacts as a false-positive result. Artifact deletion can take minutes or hours, depending on the artifacts to delete. To avoid confusion with results, do not run immediate additional API requests. + +The [artifacts for the most recent successful jobs](../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) are also kept by default. + +Example with curl: + +```shell +export GL_PROJECT_ID=48349590 + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" --request DELETE "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID/artifacts" +``` + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +glab api --method GET projects/$GL_PROJECT_ID/jobs | jq --compact-output '.[]' | jq --compact-output '.id, .artifacts' + +glab api --method DELETE projects/$GL_PROJECT_ID/artifacts +``` + +Example with the [`python-gitlab` library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#jobs): + +```python + project.artifacts.delete() +``` + +### Delete job logs + +When you delete a job log you also [erase the entire job](../api/jobs.md#erase-a-job). + +Example with the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +glab api --method GET projects/$GL_PROJECT_ID/jobs | jq --compact-output '.[]' | jq --compact-output '.id' + +4836226184 +4836226183 +4836226181 +4836226180 + +glab api --method POST projects/$GL_PROJECT_ID/jobs/4836226180/erase | jq --compact-output '.name,.status' +"generate-package: [1]" +"success" +``` + +In the `python-gitlab` API library, you must use [`job.erase()`](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#jobs) instead of `job.delete_artifacts()`. +To avoid this API call from being blocked, set the script to sleep for a short amount of time between calls +that delete the job artifact. + +```python + for job in jobs_marked_delete_artifacts: + # delete the artifacts and job log + print("DEBUG", job) + #job.delete_artifacts() + job.erase() + # Sleep for 1 second + time.sleep(1) +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +Support for creating a retention policy for job logs is proposed in [issue 374717](https://gitlab.com/gitlab-org/gitlab/-/issues/374717). + +### Inventory of job artifacts expiry settings + +To manage artifact storage, you can update or configure when an artifact expires. +The expiry setting for artifacts are configured in each job configuration in the `.gitlab-ci.yml`. + +If you have multiple projects, and depending on how job definitions are organized in the CI/CD configuration, it may be difficult to locate the expiry setting. You can use a script to search the entire CI/CD configuration. This includes access to objects that are resolved after inheriting values, like `extends` or `!reference`. +The script retrieves merged CI/CD configuration files and searches for the artifacts key to: + +- Identify the jobs that don't have an expiry setting. +- Return the expiry setting for jobs that have the artifact expiry configured. + +The following process describes how the script searches for the artifact expiry setting: + +1. To generate a merged CI/CD configuration, the script loops over all projects and calls + the [`ci_lint()`](https://python-gitlab.readthedocs.io/en/stable/gl_objects/ci_lint.html) method. +1. The `yaml_load` function loads the merged configuration into Python data structures for more analysis. +1. A dictionary that also has the key `script` identifies itself as a job definition, where the `artifacts` + key might exists. +1. If yes, the script parses the sub key `expire_in` and stores the details to print later in a Markdown table summary. + +```python + ci_job_artifacts_expiry = {} + + # Loop over projects, fetch .gitlab-ci.yml, run the linter to get the full translated config, and extract the `artifacts:` setting + # https://python-gitlab.readthedocs.io/en/stable/gl_objects/ci_lint.html + for project in projects: + project_obj = gl.projects.get(project.id) + project_name = project_obj.name + project_web_url = project_obj.web_url + try: + lint_result = project.ci_lint.get() + if lint_result.merged_yaml is None: + continue + + ci_pipeline = yaml.safe_load(lint_result.merged_yaml) + #print("Project {p} Config\n{c}\n\n".format(p=project_name, c=json.dumps(ci_pipeline, indent=4))) + + for k in ci_pipeline: + v = ci_pipeline[k] + # This is a job object with `script` attribute + if isinstance(v, dict) and 'script' in v: + print(".", end="", flush=True) # Get some feedback that it is still looping + artifacts = v['artifacts'] if 'artifacts' in v else {} + + print("Project {p} job {j} artifacts {a}".format(p=project_name, j=k, a=json.dumps(artifacts, indent=4))) + + expire_in = None + if 'expire_in' in artifacts: + expire_in = artifacts['expire_in'] + + store_key = project_web_url + '_' + k + ci_job_artifacts_expiry[store_key] = { 'project_web_url': project_web_url, + 'project_name': project_name, + 'job_name': k, + 'artifacts_expiry': expire_in} + + except Exception as e: + print(f"Exception searching artifacts on ci_pipelines: {e}".format(e=e)) + + if len(ci_job_artifacts_expiry) > 0: + print("|Project|Job|Artifact expiry|\n|-|-|-|") #Start markdown friendly table + for k, details in ci_job_artifacts_expiry.items(): + if details['job_name'][0] == '.': + continue # ignore job templates that start with a '.' + print(f'| [{ details["project_name"] }]({details["project_web_url"]}) | { details["job_name"] } | { details["artifacts_expiry"] if details["artifacts_expiry"] is not None else "❌ N/A" } |') +``` + +The script generates a Markdown summary table with project name and URL, job name, and the `artifacts:expire_in` setting, or `N/A` if not existing. It does not print job templates starting with a `.` character which are not instantiated as runtime job objects that would generate artifacts. + +```shell +export GL_GROUP_ID=56595735 + +# Script requires pyyaml too. +pip3 install python-gitlab pyyaml + +python3 get_all_cicd_config_artifacts_expiry.py + +|Project|Job|Artifact expiry| +|-|-|-| +| [Gen Job Artifacts 4](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-4) | generator | 30 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | included-job10 | 10 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | included-job1 | 1 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | included-job30 | 30 days | +| [Gen Job Artifacts with expiry and included jobs](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) | generator | 30 days | +| [Gen Job Artifacts 2](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-2) | generator | ❌ N/A | +| [Gen Job Artifacts 1](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-1) | generator | ❌ N/A | +``` + +The `get_all_cicd_config_artifacts_expiry.py` script is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +Alternatively, you can use [advanced search](search/advanced_search.md) with API requests. The following example uses the [scope: blobs](../api/search.md#scope-blobs-premium-all-2) to searches for the string `artifacts` in all `*.yml` files: + +```shell +# https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs +export GL_PROJECT_ID=48349263 + +glab api --method GET projects/$GL_PROJECT_ID/search --field "scope=blobs" --field "search=expire_in filename:*.yml" +``` + +For more information about the inventory approach, see [How GitLab can help mitigate deletion of open source container images on Docker Hub](https://about.gitlab.com/blog/2023/03/16/how-gitlab-can-help-mitigate-deletion-open-source-images-docker-hub/). + +### Set the default expiry for job artifacts in projects + +Based on the output of the `get_all_cicd_config_artifacts_expiry.py` script, you can define the [default artifact expiration](../ci/yaml/index.md#default) in your `.gitlab-ci.yml` configuration. + +```yaml +default: + artifacts: + expire_in: 1 week +``` + +### Delete old pipelines + +Pipelines do not add to the overall storage consumption, but if you want to delete them you can use the following methods. + +Example using the [GitLab CLI](../editor_extensions/gitlab_cli/index.md): + +```shell +export GL_PROJECT_ID=48349590 + +glab api --method GET projects/$GL_PROJECT_ID/pipelines | jq --compact-output '.[]' | jq --compact-output '.id,.created_at' +960031926 +"2023-08-08T22:09:52.745Z" +959884072 +"2023-08-08T18:59:47.581Z" + +glab api --method DELETE projects/$GL_PROJECT_ID/pipelines/960031926 + +glab api --method GET projects/$GL_PROJECT_ID/pipelines | jq --compact-output '.[]' | jq --compact-output '.id,.created_at' +959884072 +"2023-08-08T18:59:47.581Z" +``` + +The `created_at` key must be converted from a timestamp to Unix epoch time, +for example with `date -d '2023-08-08T18:59:47.581Z' +%s`. In the next step, the +age can be calculated with the difference between now, and the pipeline creation +date. If the age is larger than the threshold, the pipeline should be deleted. + +The following example uses a Bash script that expects `jq` and the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) installed, and authorized, and the exported environment variable `GL_PROJECT_ID`. + +The full script `get_cicd_pipelines_compare_age_threshold_example.sh` is located in the [GitLab API with Linux Shell](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-linux-shell) project. + +```shell +#/bin/bash + +CREATED_AT_ARR=$(glab api --method GET projects/$GL_PROJECT_ID/pipelines | jq --compact-output '.[]' | jq --compact-output '.created_at' | jq --raw-output @sh) + +for row in ${CREATED_AT_ARR[@]} +do + stripped=$(echo $row | xargs echo) + #echo $stripped #DEBUG + + CREATED_AT_TS=$(date -d "$stripped" +%s) + NOW=$(date +%s) + + AGE=$(($NOW-$CREATED_AT_TS)) + AGE_THRESHOLD=$((90*24*60*60)) # 90 days + + if [ $AGE -gt $AGE_THRESHOLD ]; + then + echo "Pipeline age $AGE older than threshold $AGE_THRESHOLD, should be deleted." + # TODO call glab to delete the pipeline. Needs an ID collected from the glab call above. + else + echo "Pipeline age $AGE not older than threshold $AGE_THRESHOLD. Ignore." + fi +done +``` + +You can use the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html#project-pipelines) and +the `created_at` attribute to implement a similar algorithm that compares the job artifact age: + +```python + # ... + + for pipeline in project.pipelines.list(iterator=True): + pipeline_obj = project.pipelines.get(pipeline.id) + print("DEBUG: {p}".format(p=json.dumps(pipeline_obj.attributes, indent=4))) + + created_at = datetime.datetime.strptime(pipeline.created_at, '%Y-%m-%dT%H:%M:%S.%fZ') + now = datetime.datetime.now() + age = (now - created_at).total_seconds() + + threshold_age = 90 * 24 * 60 * 60 + + if (float(age) > float(threshold_age)): + print("Deleting pipeline", pipeline.id) + pipeline_obj.delete() +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python project](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/). + +Automatically deleting old pipelines in GitLab is tracked in [this feature proposal](https://gitlab.com/gitlab-org/gitlab/-/issues/338480). + +## Manage storage for Container Registries + +Container registries are available [in a project](../api/container_registry.md#within-a-project) or [in a group](../api/container_registry.md#within-a-group). Both locations require analysis and cleanup strategies. + +The following example uses using `curl` and `jq` for a project: + +```shell +export GL_PROJECT_ID=48057080 + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/$GL_PROJECT_ID/registry/repositories" | jq --compact-output '.[]' | jq --compact-output '.id,.location' | jq +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" + +curl --silent --header "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/registry/repositories/4435617?size=true" | jq --compact-output '.id,.location,.size' +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" +3401613 +``` + +The following example uses the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) for a project: + +```shell +export GL_PROJECT_ID=48057080 + +glab api --method GET projects/$GL_PROJECT_ID/registry/repositories | jq --compact-output '.[]' | jq --compact-output '.id,.location' +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" + +glab api --method GET registry/repositories/4435617 --field='size=true' | jq --compact-output '.id,.location,.size' +4435617 +"registry.gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator" +3401613 + +glab api --method GET projects/$GL_PROJECT_ID/registry/repositories/4435617/tags | jq --compact-output '.[]' | jq --compact-output '.name' +"latest" + +glab api --method GET projects/$GL_PROJECT_ID/registry/repositories/4435617/tags/latest | jq --compact-output '.name,.created_at,.total_size' +"latest" +"2023-08-07T19:20:20.894+00:00" +3401613 +``` + +A similar automation shell script is created in the [delete old pipelines](#delete-old-pipelines) section. + +The `python-gitlab` API library provides bulk deletion interfaces explained in the next section. + +### Delete container images in bulk + +When you [delete container image tags in bulk](../api/container_registry.md#delete-registry-repository-tags-in-bulk), +you can configure: + +- The matching regular expressions for tag names and images to keep (`name_regex_keep`) or delete (`name_regex_delete`) +- The number of image tags to keep matching the tag name (`keep_n`) +- The number of days before an image tag can be deleted (`older_than`) + +WARNING: +On GitLab.com, due to the scale of the Container Registry, the number of tags deleted by this API is limited. +If your Container Registry has a large number of tags to delete, only some of them are deleted. You might need +to call the API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](#cleanup-policy-for-containers) instead. + +The following example uses the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/repository_tags.html) to fetch a list of tags, and calls the `delete_in_bulk()` method with filter parameters. + +```python + repositories = project.repositories.list(iterator=True, size=True) + if len(repositories) > 0: + repository = repositories.pop() + tags = repository.tags.list() + + # Cleanup: Keep only the latest tag + repository.tags.delete_in_bulk(keep_n=1) + # Cleanup: Delete all tags older than 1 month + repository.tags.delete_in_bulk(older_than="1m") + # Cleanup: Delete all tags matching the regex `v.*`, and keep the latest 2 tags + repository.tags.delete_in_bulk(name_regex_delete="v.+", keep_n=2) +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located +in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. + +### Cleanup policy for containers + +Use the project REST API endpoint to [create cleanup policies](packages/container_registry/reduce_container_registry_storage.md#use-the-cleanup-policy-api). The following example uses the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) to create a cleanup policy. + +To send the attributes as a body parameter, you must: + +- Use the `--input -` parameter to read from the standard input. +- Set the `Content-Type` header. + +```shell +export GL_PROJECT_ID=48057080 + +echo '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":".*","name_regex_keep":".*-main"}}' | glab api --method PUT --header 'Content-Type: application/json;charset=UTF-8' projects/$GL_PROJECT_ID --input - + +... + + "container_expiration_policy": { + "cadence": "1month", + "enabled": true, + "keep_n": 1, + "older_than": "14d", + "name_regex": ".*", + "name_regex_keep": ".*-main", + "next_run_at": "2023-09-08T21:16:25.354Z" + }, + +``` + +After you set up the cleanup policy, all container images that match your specifications are deleted automatically. You do not need additional API automation scripts. + +### Optimize container images + +You can optimize container images to reduce the image size and overall storage consumption in the container registry. Learn more in the [pipeline efficiency documentation](../ci/pipelines/pipeline_efficiency.md#optimize-docker-images). + +## Manage storage for Package Registry + +Package registries are available [in a project](../api/packages.md#within-a-project) or [in a group](../api/packages.md#within-a-group). + +### List packages and files + +The following example shows fetching packages from a defined project ID using the [GitLab CLI](../editor_extensions/gitlab_cli/index.md). The result set is an array of dictionary items that can be filtered with the `jq` command chain. + +```shell +# https://gitlab.com/gitlab-de/playground/container-package-gen-group/generic-package-generator +export GL_PROJECT_ID=48377643 + +glab api --method GET projects/$GL_PROJECT_ID/packages | jq --compact-output '.[]' | jq --compact-output '.id,.name,.package_type' +16669383 +"generator" +"generic" +16671352 +"generator" +"generic" +16672235 +"generator" +"generic" +16672237 +"generator" +"generic" +``` + +Use the package ID to inspect the files and their size in the package. + +```shell +glab api --method GET projects/$GL_PROJECT_ID/packages/16669383/package_files | jq --compact-output '.[]' | + jq --compact-output '.package_id,.file_name,.size' + +16669383 +"nighly.tar.gz" +10487563 +``` + +A similar automation shell script is created in the [delete old pipelines](#delete-old-pipelines) section. + +The following script example uses the `python-gitlab` library to fetch all packages in a loop, +and loops over its package files to print the `file_name` and `size` attributes. + +```python + packages = project.packages.list(order_by="created_at") + + for package in packages: + + package_files = package.package_files.list() + for package_file in package_files: + print("Package name: {p} File name: {f} Size {s}".format( + p=package.name, f=package_file.file_name, s=render_size_mb(package_file.size))) +``` + +### Delete packages + +[Deleting a file in a package](../api/packages.md#delete-a-package-file) can corrupt the package. You should delete the package when performing automated cleanup maintenance. + +To delete a package, use the [GitLab CLI](../editor_extensions/gitlab_cli/index.md) to change the `--method` +parameter to `DELETE`: + +```shell +glab api --method DELETE projects/$GL_PROJECT_ID/packages/16669383 +``` + +To calculate the package size and compare it against a size threshold, you can use the `python-gitlab` library +to extend the code described in the [list packages and files](#list-packages-and-files) section. + +The following code example also calculates the package age and deletes the package when the conditions match: + +```python + packages = project.packages.list(order_by="created_at") + for package in packages: + package_size = 0.0 + + package_files = package.package_files.list() + for package_file in package_files: + print("Package name: {p} File name: {f} Size {s}".format( + p=package.name, f=package_file.file_name, s=render_size_mb(package_file.size))) + + package_size =+ package_file.size + + print("Package size: {s}\n\n".format(s=render_size_mb(package_size))) + + threshold_size = 10 * 1024 * 1024 + + if (package_size > float(threshold_size)): + print("Package size {s} > threshold {t}, deleting package.".format( + s=render_size_mb(package_size), t=render_size_mb(threshold_size))) + package.delete() + + threshold_age = 90 * 24 * 60 * 60 + package_age = created_at = calculate_age(package.created_at) + + if (float(package_age > float(threshold_age))): + print("Package age {a} > threshold {t}, deleting package.".format( + a=render_age_time(package_age), t=render_age_time(threshold_age))) + package.delete() +``` + +The code generates the following output that you can use for further analysis: + +```shell +Package name: generator File name: nighly.tar.gz Size 10.0017 +Package size: 10.0017 +Package size 10.0017 > threshold 10.0000, deleting package. + +Package name: generator File name: 1-nightly.tar.gz Size 1.0004 +Package size: 1.0004 + +Package name: generator File name: 10-nightly.tar.gz Size 10.0018 +Package name: generator File name: 20-nightly.tar.gz Size 20.0033 +Package size: 20.0033 +Package size 20.0033 > threshold 10.0000, deleting package. +``` + +The full example of the script `get_all_projects_top_level_namespace_storage_analysis_cleanup_example.py` is located in the [GitLab API with Python](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-api-python/) project. + +### Dependency Proxy + +Review the [cleanup policy](packages/dependency_proxy/reduce_dependency_proxy_storage.md#cleanup-policies) and how to [purge the cache using the API](packages/dependency_proxy/reduce_dependency_proxy_storage.md#use-the-api-to-clear-the-cache) + +## Community resources + +These resources are not officially supported. Ensure to test scripts and tutorials before running destructive cleanup commands that may not be reverted. + +- Forum topic: [Storage management automation resources](https://forum.gitlab.com/t/storage-management-automation-resources/) +- Script: [GitLab Storage Analyzer](https://gitlab.com/gitlab-de/use-cases/gitlab-api/gitlab-storage-analyzer), unofficial project by the [GitLab Developer Evangelism team](https://gitlab.com/gitlab-de/). You find similar code examples in this documentation how-to here. + +## Testing for storage management automation + +To test storage management automation, you might need to generate test data, or populate +storage to verify that the analysis and deletion works as expected. The following sections +provide tools and tips about testing and generating storage blobs in a short amount of time. + +### Generate job artifacts + +Create a test project to generate fake artifact blobs using CI/CD job matrix builds. Add a CI/CD pipeline to generate artifacts on a daily basis + +1. Create a new project. +1. Add the following snippet to `.gitlab-ci.yml` to include the job artifact generator configuration. + + ```yaml + include: + - remote: https://gitlab.com/gitlab-de/use-cases/efficiency/job-artifact-generator/-/raw/main/.gitlab-ci.yml + ``` + +1. [Configure pipeline schedules](../ci/pipelines/schedules.md#add-a-pipeline-schedule). +1. [Trigger the pipeline manually](../ci/pipelines/schedules.md#run-manually). + +Alternatively, reduce the 86 MB daily generated MB to different values in the `MB_COUNT` variable. + +```yaml +include: + - remote: https://gitlab.com/gitlab-de/use-cases/efficiency/job-artifact-generator/-/raw/main/.gitlab-ci.yml + +generator: + parallel: + matrix: + - MB_COUNT: [1, 5, 10, 20, 50] + +``` + +For more information, see the [Job Artifact Generator README](https://gitlab.com/gitlab-de/use-cases/efficiency/job-artifact-generator), with an [example group](https://gitlab.com/gitlab-de/playground/artifact-gen-group). + +### Generate job artifacts with expiry + +The project CI/CD configuration specifies job definitions in: + +- The main `.gitlab-ci.yml` configuration file. +- The `artifacts:expire_in` setting. +- Project files and templates. + +To test the analysis scripts, the [`gen-job-artifacts-expiry-included-jobs`](https://gitlab.com/gitlab-de/playground/artifact-gen-group/gen-job-artifacts-expiry-included-jobs) project provides an example configuration. + +```yaml +# .gitlab-ci.yml +include: + - include_jobs.yml + +default: + artifacts: + paths: + - '*.txt' + +.gen-tmpl: + script: + - dd if=/dev/urandom of=${$MB_COUNT}.txt bs=1048576 count=${$MB_COUNT} + +generator: + extends: [.gen-tmpl] + parallel: + matrix: + - MB_COUNT: [1, 5, 10, 20, 50] + artifacts: + untracked: false + when: on_success + expire_in: 30 days + +# include_jobs.yml +.includeme: + script: + - dd if=/dev/urandom of=1.txt bs=1048576 count=1 + +included-job10: + script: + - echo "Servus" + - !reference [.includeme, script] + artifacts: + untracked: false + when: on_success + expire_in: 10 days + +included-job1: + script: + - echo "Gruezi" + - !reference [.includeme, script] + artifacts: + untracked: false + when: on_success + expire_in: 1 days + +included-job30: + script: + - echo "Grias di" + - !reference [.includeme, script] + artifacts: + untracked: false + when: on_success + expire_in: 30 days +``` + +### Generate container images + +The example group [`container-package-gen-group`](https://gitlab.com/gitlab-de/playground/container-package-gen-group) provides projects that: + +- Use a base image in Dockerfile to build a new image. +- Include the `Docker.gitlab-ci.yml` template to build images on GitLab.com SaaS. +- Configure pipeline schedules to generate new images daily. + +Example projects available to fork: + +- [`docker-alpine-generator`](https://gitlab.com/gitlab-de/playground/container-package-gen-group/docker-alpine-generator) +- [`docker-python-generator`](https://gitlab.com/gitlab-de/playground/container-package-gen-group/docker-python-generator) + +### Generate generic packages + +The example project [`generic-package-generator`](https://gitlab.com/gitlab-de/playground/container-package-gen-group/generic-package-generator) provides projects that: + +- Generate a random text blob, and create a tarball with the current Unix timestamp as release version. +- Upload the tarball into the generic package registry, using the Unix timestamp as release version. + +To generate generic packages, you can use this standalone `.gitlab-ci.yml` configuration: + +```yaml +generate-package: + parallel: + matrix: + - MB_COUNT: [1, 5, 10, 20] + before_script: + - apt update && apt -y install curl + script: + - dd if=/dev/urandom of="${MB_COUNT}.txt" bs=1048576 count=${MB_COUNT} + - tar czf "generated-$MB_COUNT-nighly-`date +%s`.tar.gz" "${MB_COUNT}.txt" + - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file "generated-$MB_COUNT-nighly-`date +%s`.tar.gz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/generator/`date +%s`/${MB_COUNT}-nightly.tar.gz"' + + artifacts: + paths: + - '*.tar.gz' + +``` + +### Generate storage usage with forks + +Use the following projects to test storage usage with [cost factors for forks](usage_quotas.md#view-project-fork-storage-usage): + +- Fork [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) into a new namespace or group (includes LFS, Git repository). +- Fork [`gitlab-com/www-gitlab-com`](https://gitlab.com/gitlab-com/www-gitlab-comgitlab-com/www-gitlab-com) into a new namespace or group. diff --git a/doc/user/tasks.md b/doc/user/tasks.md index ecd5ef0c42f..c340bb736ef 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tasks **(FREE)** +# Tasks **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default. > - [Creating, editing, and deleting tasks](https://gitlab.com/groups/gitlab-org/-/epics/7169) introduced in GitLab 15.0. @@ -269,7 +269,7 @@ To add a task to a milestone: If a task already belongs to a milestone, the dropdown list shows the current milestone. 1. From the dropdown list, select the milestone to be associated with the task. -## Set task weight **(PREMIUM)** +## Set task weight **(PREMIUM ALL)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. @@ -287,7 +287,7 @@ To set issue weight of a task: 1. Next to **Weight**, enter a whole, positive number. 1. Select the close icon (**{close}**). -## Add a task to an iteration **(PREMIUM)** +## Add a task to an iteration **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) to feature flag named `work_items_mvc` in GitLab 15.7. Disabled by default. @@ -360,6 +360,75 @@ To copy the task's email address: 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**. +## Confidential tasks + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8410) in GitLab 15.3. + +Confidential tasks are tasks visible only to members of a project with +[sufficient permissions](#who-can-see-confidential-tasks). +You can use confidential tasks to keep security vulnerabilities private or prevent surprises from +leaking out. + +### Make a task confidential + +By default, tasks are public. +You can make a task confidential when you create or edit it. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- If the task has a parent issue which is non-confidential, and you want to make the issue confidential, + you must first make all the child tasks confidential. + A [confidential issue](project/issues/confidential_issues.md) can have only confidential children. + +#### In a new task + +When you create a new task, a checkbox right below the text area is available to mark the +task as confidential. + +Check that box and select **Create task**. + +#### In an existing task + +To change the confidentiality of an existing task: + +1. [Open the task](#view-tasks). +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Turn on confidentiality**. + +### Who can see confidential tasks + +When a task is made confidential, only users with at least the Reporter role for the project have +access to the task. +Users with Guest or [Minimal](permissions.md#users-with-minimal-access) roles can't access +the task even if they were actively participating before the change. + +However, a user with the **Guest role** can create confidential tasks, but can only view the ones +that they created themselves. + +Users with the Guest role or non-members can read the confidential task if they are assigned to the task. +When a Guest user or non-member is unassigned from a confidential task, they can no longer view it. + +Confidential tasks are hidden in search results for users without the necessary permissions. + +### Confidential task indicators + +Confidential tasks are visually different from regular tasks in a few ways. +Wherever tasks are listed, you can see the confidential (**{eye-slash}**) icon +next to the tasks that are marked as confidential. + +If you don't have [enough permissions](#who-can-see-confidential-tasks), +you cannot see confidential tasks at all. + +Likewise, while inside the task, you can see the confidential (**{eye-slash}**) icon right next to +the breadcrumbs. + +Every change from regular to confidential and vice versa, is indicated by a +system note in the task's comments, for example: + +> - **{eye-slash}** Jo Garcia made the issue confidential 5 minutes ago +> - **{eye}** Jo Garcia made the issue visible to everyone just now + ## Two-column layout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. diff --git a/doc/user/todos.md b/doc/user/todos.md index 97f67c67671..eedd5d8a510 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# To-Do List **(FREE)** +# To-Do List **(FREE ALL)** Your *To-Do List* is a chronological list of items waiting for your input. The items are known as *to-do items*. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index d119044930a..ade99a5fef8 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -5,7 +5,7 @@ group: Utilization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Storage usage quota **(FREE)** +# Storage usage quota **(FREE ALL)** Storage usage statistics are available for projects and namespaces. You can use that information to manage storage usage within the applicable quotas. @@ -112,6 +112,10 @@ Depending on your role, you can also use the following methods to manage or redu - [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). - [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). - [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). +- [Manage artifact expiration period](../ci/yaml/index.md#artifactsexpire_in). +- [Reduce build artifact storage](../ci/jobs/job_artifacts.md#delete-job-log-and-artifacts). + +To automate storage usage analysis and management, see the [storage management automation](storage_management_automation.md) documentation. ## Manage your transfer usage @@ -161,7 +165,7 @@ example, no additional storage has yet been purchased. To remove the read-only state from the Red and Green projects, 50 GB additional storage is purchased. Assuming the Green and Red projects' repositories and LFS grow past the 10 GB quota, the purchased storage -available decreases. All projects remain read-only because 40 GB purchased storage is available: +available decreases. All projects no longer have the read-only status because 40 GB purchased storage is available: 50 GB (purchased storage) - 10 GB (total excess storage used). | Repository | Storage used | Excess storage | Quota | Status | @@ -205,6 +209,20 @@ To prevent exceeding the namespace storage quota, you can: - [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. - [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. +### View project fork storage usage + +A cost factor is applied to the storage consumed by project forks so that forks consume less namespace storage than their actual size. + +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 **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/version.md b/doc/user/version.md new file mode 100644 index 00000000000..b7846988e06 --- /dev/null +++ b/doc/user/version.md @@ -0,0 +1,23 @@ +--- +stage: none +group: none +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 +--- + +# Find the GitLab version + +Find the version of GitLab you're running. + +## For self-managed GitLab + +- On the left sidebar, at the bottom, select **Help**. + +The version is displayed at the top of the dialog. + +## For GitLab.com + +- Go to <https://gitlab.com/help>. + +The version is displayed at the top of the page. For example, +`GitLab Enterprise Edition 16.3.0-pre 1e04d6b7fa9` indicates a pre-release +version of GitLab 16.3. diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md new file mode 100644 index 00000000000..3900c95e41a --- /dev/null +++ b/doc/user/workspace/configuration.md @@ -0,0 +1,207 @@ +--- +stage: Create +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)** + +> - [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. + +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 `remote_development_feature_flag`. +On GitLab.com, this feature is available. +The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. +To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). + +You can use [workspaces](index.md) to create and manage isolated development environments for your GitLab projects. +Each workspace includes its own set of dependencies, libraries, and tools, +which you can customize to meet the specific needs of each project. + +## Set up a workspace + +### Prerequisites + +- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. + See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features). +- Ensure autoscaling for the Kubernetes cluster is enabled. +- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) + is defined so that volumes can be dynamically provisioned for each workspace. +- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`) + and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and + `workspaces.example.dev` to the load balancer exposed by the Ingress controller. +- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). +- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md). +- Configure remote development settings for the GitLab agent with this snippet and update `dns_zone` as needed: + + ```yaml + remote_development: + enabled: true + dns_zone: "workspaces.example.dev" + ``` + + 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. + 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). + +### Create a workspace + +To create a workspace: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +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. +1. Select **Create workspace**. + +The workspace might take a few minutes to start. +To open the workspace, under **Preview**, select the workspace. +You also have access to the terminal and can install any necessary dependencies. + +## Connect to a workspace with SSH + +Prerequisites: + +- SSH must be enabled for the workspace. +- You must have a TCP load balancer that points to [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy). + +To connect to a workspace with an SSH client: + +1. Run this command: + + ```shell + ssh <workspace_name>@<ssh_proxy> + ``` + +1. For the password, enter your personal access token with at least the `read_api` scope. + +When you connect to `gitlab-workspaces-proxy` through the TCP load balancer, +`gitlab-workspaces-proxy` examines the username (workspace name) and interacts with GitLab to verify: + +- The personal access token +- User access to the workspace + +### Set up `gitlab-workspaces-proxy` for SSH connections + +Prerequisite: + +- You must have an SSH host key for client verification. + +SSH is now enabled by default in [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy). +To set up `gitlab-workspaces-proxy` with the GitLab Helm chart: + +1. Run this command: + + ```shell + ssh-keygen -f ssh-host-key -N '' -t rsa + export SSH_HOST_KEY=$(pwd)/ssh-host-key + ``` + +1. Install `gitlab-workspaces-proxy` with the generated SSH host key: + + ```shell + helm upgrade --install gitlab-workspaces-proxy \ + gitlab-workspaces-proxy/gitlab-workspaces-proxy \ + --version 0.1.8 \ + --namespace=gitlab-workspaces \ + --create-namespace \ + --set="auth.client_id=${CLIENT_ID}" \ + --set="auth.client_secret=${CLIENT_SECRET}" \ + --set="auth.host=${GITLAB_URL}" \ + --set="auth.redirect_uri=${REDIRECT_URI}" \ + --set="auth.signing_key=${SIGNING_KEY}" \ + --set="ingress.host.workspaceDomain=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \ + --set="ingress.host.wildcardDomain=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \ + --set="ingress.tls.workspaceDomainCert=$(cat ${WORKSPACES_DOMAIN_CERT})" \ + --set="ingress.tls.workspaceDomainKey=$(cat ${WORKSPACES_DOMAIN_KEY})" \ + --set="ingress.tls.wildcardDomainCert=$(cat ${WILDCARD_DOMAIN_CERT})" \ + --set="ingress.tls.wildcardDomainKey=$(cat ${WILDCARD_DOMAIN_KEY})" \ + --set="ssh.host_key=$(cat ${SSH_HOST_KEY})" \ + --set="ingress.className=nginx" + ``` + +### Update your runtime images + +To update your runtime images for SSH connections: + +1. Install [`sshd`](https://man.openbsd.org/sshd.8) in your runtime images. +1. Create a user named `gitlab-workspaces` to allow access to your container without a password. + +```Dockerfile +FROM golang:1.20.5-bullseye + +# Install `openssh-server` and other dependencies +RUN apt update \ + && apt upgrade -y \ + && apt install openssh-server sudo curl git wget software-properties-common apt-transport-https --yes \ + && rm -rf /var/lib/apt/lists/* + +# Permit empty passwords +RUN sed -i 's/nullok_secure/nullok/' /etc/pam.d/common-auth +RUN echo "PermitEmptyPasswords yes" >> /etc/ssh/sshd_config + +# Generate a workspace host key +RUN ssh-keygen -A +RUN chmod 775 /etc/ssh/ssh_host_rsa_key && \ + chmod 775 /etc/ssh/ssh_host_ecdsa_key && \ + chmod 775 /etc/ssh/ssh_host_ed25519_key + +# Create a `gitlab-workspaces` user +RUN useradd -l -u 5001 -G sudo -md /home/gitlab-workspaces -s /bin/bash gitlab-workspaces +RUN passwd -d gitlab-workspaces +ENV HOME=/home/gitlab-workspaces +WORKDIR $HOME +RUN mkdir -p /home/gitlab-workspaces && chgrp -R 0 /home && chmod -R g=u /etc/passwd /etc/group /home + +# Allow sign-in access to `/etc/shadow` +RUN chmod 775 /etc/shadow + +USER gitlab-workspaces +``` + +## Disable remote development in the GitLab agent for Kubernetes + +You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab. +To disable remote development in the GitLab agent configuration, set this property: + +```yaml +remote_development: + enabled: false +``` + +If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes. + +## Related topics + +- [Quickstart guide for GitLab remote development workspaces](https://go.gitlab.com/AVKFvy) +- [Set up your infrastructure for on-demand, cloud-based development environments in GitLab](https://go.gitlab.com/dp75xo) + +## Troubleshooting + +### `Failed to renew lease` when creating a workspace + +You might not be able to create a workspace due to a known issue in the GitLab agent for Kubernetes. +The following error message might appear in the agent's log: + +```plaintext +{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX} +``` + +This issue occurs when an agent instance cannot renew its leadership lease, which results +in the shutdown of leader-only modules including the `remote_development` module. +To resolve this issue, restart the agent instance. diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md new file mode 100644 index 00000000000..43140a622e0 --- /dev/null +++ b/doc/user/workspace/create_image.md @@ -0,0 +1,119 @@ +--- +stage: Create +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)** + +> - [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. + +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 `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. + +WARNING: +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). + +In this tutorial, you'll learn how to create a custom workspace image that supports arbitrary user IDs. +You can then use this custom image with any [workspace](index.md) you create in GitLab. + +To create a custom workspace image that supports arbitrary user IDs, you'll: + +1. [Create a base Dockerfile](#create-a-base-dockerfile). +1. [Add support for arbitrary user IDs](#add-support-for-arbitrary-user-ids). +1. [Build the custom workspace image](#build-the-custom-workspace-image). +1. [Push the custom workspace image to the GitLab Container Registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). +1. [Use the custom workspace image in GitLab](#use-the-custom-workspace-image-in-gitlab). + +## Prerequisites + +- A GitLab account with permission to create and push container images to the GitLab Container Registry +- Docker installation + +## Create a base Dockerfile + +To create a base Dockerfile for the container image, let's use the Python `3.11-slim-bullseye` image from Docker Hub: + +```Dockerfile +FROM python:3.11-slim-bullseye +``` + +Next, you'll modify this base image. + +## Add support for arbitrary user IDs + +To add support for arbitrary user IDs to the base image, let's: + +1. Add a new `gitlab-workspaces` user with a `5001` user ID. +1. Set the necessary directory permissions. + +```Dockerfile +RUN useradd -l -u 5001 -G sudo -md /home/gitlab-workspaces -s /bin/bash -p gitlab-workspaces gitlab-workspaces + +ENV HOME=/home/gitlab-workspaces + +WORKDIR $HOME + +RUN mkdir -p /home/gitlab-workspaces && chgrp -R 0 /home && chmod -R g=u /etc/passwd /etc/group /home + +USER 5001 +``` + +Now that the image supports arbitrary user IDs, it's time to build the custom workspace image. + +## Build the custom workspace image + +To build the custom workspace image, run this command: + +```shell +docker build -t my-gitlab-workspace . +``` + +When the build is complete, you can test the image locally: + +```shell +docker run -ti my-gitlab-workspace sh +``` + +You should now be able to run commands as the `gitlab-workspaces` user. + +## Push the custom workspace image to the GitLab Container Registry + +To push the custom workspace image to the GitLab Container Registry: + +1. Sign in to your GitLab account: + + ```shell + docker login registry.gitlab.com + ``` + +1. Tag the image with the GitLab Container Registry URL: + + ```shell + docker tag my-gitlab-workspace registry.gitlab.com/your-namespace/my-gitlab-workspace:latest + ``` + +1. Push the image to the GitLab Container Registry: + + ```shell + docker push registry.gitlab.com/your-namespace/my-gitlab-workspace:latest + ``` + +Now that you've pushed the custom workspace image to the GitLab Container Registry, you can use the image in GitLab. + +## Use the custom workspace image in GitLab + +To use the custom workspace image in GitLab, in your project's `.devfile.yaml`, update the container image: + +```yaml +schemaVersion: 2.2.0 +components: + - name: tooling-container + attributes: + gl/inject-editor: true + container: + image: registry.gitlab.com/your-namespace/my-gitlab-workspace:latest +``` + +You're all set! You can now use this custom image with any [workspace](index.md) you create in GitLab. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index a101e5f5f8c..51e3e905a92 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -4,82 +4,76 @@ 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)** +# Workspaces (Beta) **(PREMIUM ALL)** > - [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. 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 `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. +To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. +On GitLab.com, this feature is available. +The feature is not ready for production use. WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. +To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). -A workspace is a virtual sandbox environment for your code in GitLab. You can use workspaces to create and manage isolated development environments for your GitLab projects. These environments ensure that different projects don't interfere with each other. +A workspace is a virtual sandbox environment for your code in GitLab. +You can use workspaces to create and manage isolated development environments for your GitLab projects. +These environments ensure that different projects don't interfere with each other. -Each workspace includes its own set of dependencies, libraries, and tools, which you can customize to meet the specific needs of each project. Workspaces use the AMD64 architecture. +Each workspace includes its own set of dependencies, libraries, and tools, +which you can customize to meet the specific needs of each project. +Workspaces use the AMD64 architecture. -For a demo of this feature, see [GitLab Workspaces Demo](https://go.gitlab.com/qtu66q). +## Workspaces and projects -## Set up a workspace +Workspaces are scoped to a project. +When you [create a workspace](configuration.md#set-up-a-workspace), you must: -### Prerequisites +- Assign the workspace to a specific project. +- Select a project with a [`.devfile.yaml`](#devfile) file. -- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features). -- Ensure autoscaling for the Kubernetes cluster is enabled. -- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) is defined so that volumes can be dynamically provisioned for each workspace. -- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`), and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and `workspaces.example.dev` to the load balancer exposed by the Ingress controller. -- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). -- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md). -- Configure remote development settings for the GitLab agent with this snippet, and update `dns_zone` as needed: +The workspace can then interact with the GitLab API based on the permissions granted to the current user. - ```yaml - remote_development: - enabled: true - dns_zone: "workspaces.example.dev" - ``` +### Open and manage workspaces from a 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](#devfile): - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to 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](#example-configurations). -- Ensure the container images used in the devfile support [arbitrary user IDs](#arbitrary-user-ids). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125331) in GitLab 16.2. -### Create a workspace +To open a workspace from a file or the repository file list: -To create a workspace: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. In the upper right, select **Edit**. +1. From the dropdown list, under **Your workspaces**, select the workspace. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -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. -1. Select **Create workspace**. +From the dropdown list, you can also: -The workspace might take a few minutes to start. To access the workspace, under **Preview**, select the workspace link. -You also have access to the terminal and can install any necessary dependencies. +- Restart, stop, or terminate an existing workspace. +- Create a new workspace. -## Deleting data associated with a workspace +### Deleting data associated with a workspace When you delete a project, agent, user, or token associated with a workspace: - The workspace is deleted from the user interface. -- In the Kubernetes cluster, the running workspace resources become orphaned. +- In the Kubernetes cluster, the running workspace resources become orphaned and are not automatically deleted. To clean up orphaned resources, an administrator must manually delete the workspace in Kubernetes. -For more information about our plans to change the current behavior, see [issue 414384](https://gitlab.com/gitlab-org/gitlab/-/issues/414384). +[Issue 414384](https://gitlab.com/gitlab-org/gitlab/-/issues/414384) proposes to change this behavior. ## Devfile -A devfile is a file that defines a development environment by specifying the necessary tools, languages, runtimes, and other components for a GitLab project. +A devfile is a file that defines a development environment by specifying the necessary +tools, languages, runtimes, and other components for a GitLab project. -Workspaces have built-in support for devfiles. You can specify a devfile for your project in the GitLab configuration file. The devfile is used to automatically configure the development environment with the defined specifications. +Workspaces have built-in support for devfiles. +You can specify a devfile for your project in the GitLab configuration file. +The devfile is used to automatically configure the development environment with the defined specifications. -This way, you can create consistent and reproducible development environments regardless of the machine or platform you use. +This way, you can create consistent and reproducible development environments +regardless of the machine or platform you use. ### Relevant schema properties @@ -123,66 +117,63 @@ components: For more information, see the [devfile documentation](https://devfile.io/docs/2.2.0/devfile-schema). For other examples, see the [`examples` projects](https://gitlab.com/gitlab-org/remote-development/examples). -This container image is for demonstration purposes only. To use your own container image, see [Arbitrary user IDs](#arbitrary-user-ids). +This container image is for demonstration purposes only. +To use your own container image, see [Arbitrary user IDs](#arbitrary-user-ids). ## Web IDE -Workspaces are bundled with the Web IDE by default. The Web IDE is the only code editor available for workspaces. +Workspaces are bundled with the Web IDE by default. +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). +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 -You cannot create 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. +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. From a workspace, you can clone any repository manually. ## Pod interaction in a cluster -Workspaces run as pods in a Kubernetes cluster. GitLab does not impose any restrictions on the manner in which pods interact with each other. +Workspaces run as pods in a Kubernetes cluster. +GitLab does not impose any restrictions on the manner in which pods interact with each other. Because of this requirement, you might want to isolate this feature from other containers in your cluster. ## Network access and workspace authorization -It's the client's responsibility to restrict network access to the Kubernetes control plane as GitLab does not have control over the API. +It's the client's responsibility to restrict network access to the Kubernetes control plane +because GitLab does not have control over the API. -Only the workspace creator can access the workspace and any endpoints exposed in that workspace. The workspace creator is only authorized to access the workspace after user authentication with OAuth. +Only the workspace creator can access the workspace and any endpoints exposed in that workspace. +The workspace creator is only authorized to access the workspace after user authentication with OAuth. ## Compute resources and volume storage -When you stop a workspace, the compute resources for that workspace are scaled down to zero. However, the volume provisioned for the workspace still exists. +When you stop a workspace, the compute resources for that workspace are scaled down to zero. +However, the volume provisioned for the workspace still exists. To delete the provisioned volume, you must terminate the workspace. -## Disable remote development in the GitLab agent for Kubernetes - -You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab. To disable remote development in the GitLab agent configuration, set this property: - -```yaml -remote_development: - enabled: false -``` - -If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes. - ## Arbitrary user IDs -You can provide your own container image, which can run as any Linux user ID. It's not possible for GitLab to predict the Linux user ID for a container image. -GitLab uses the Linux root group ID permission to create, update, or delete files in a container. The container runtime used by the Kubernetes cluster must ensure all containers have a default Linux group ID of `0`. - -If you have a container image that does not support arbitrary user IDs, you cannot create, update, or delete files in a workspace. To create a container image that supports arbitrary user IDs, see the [OpenShift documentation](https://docs.openshift.com/container-platform/4.12/openshift_images/create-images.html#use-uid_create-images). +You can provide your own container image, which can run as any Linux user ID. -## Troubleshooting +It's not possible for GitLab to predict the Linux user ID for a container image. +GitLab uses the Linux root group ID permission to create, update, or delete files in a container. +The container runtime used by the Kubernetes cluster must ensure all containers have a default Linux group ID of `0`. -When working with workspaces, you might encounter the following issues. +If you have a container image that does not support arbitrary user IDs, +you cannot create, update, or delete files in a workspace. +To create a container image that supports arbitrary user IDs, +see [Create a custom workspace image that supports arbitrary user IDs](../workspace/create_image.md). -### `Failed to renew lease` when creating a workspace +For more information, see the +[OpenShift documentation](https://docs.openshift.com/container-platform/4.12/openshift_images/create-images.html#use-uid_create-images). -You might not be able to create a workspace due to a known issue in the GitLab agent for Kubernetes. The following error message might appear in the agent's log: - -```plaintext -{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX} -``` +## Related topics -This issue occurs when an agent instance cannot renew its leadership lease, which results in the shutdown of leader-only modules including the `remote_development` module. To resolve this issue, restart the agent instance. +- [GitLab workspaces demo](https://go.gitlab.com/qtu66q) |
