diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-06-20 13:43:29 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-06-20 13:43:29 +0300 |
commit | 3b1af5cc7ed2666ff18b718ce5d30fa5a2756674 (patch) | |
tree | 3bc4a40e0ee51ec27eabf917c537033c0c5b14d4 /doc/user | |
parent | 9bba14be3f2c211bf79e15769cd9b77bc73a13bc (diff) |
Add latest changes from gitlab-org/gitlab@16-1-stable-eev16.1.0-rc42
Diffstat (limited to 'doc/user')
339 files changed, 4749 insertions, 3016 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md index 31cc9825452..69bf4ff30f1 100644 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ b/doc/user/admin_area/analytics/dev_ops_reports.md @@ -12,8 +12,9 @@ from planning to monitoring. To see DevOps Reports: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Analytics > DevOps Reports**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Analytics > DevOps Reports**. ## DevOps Score @@ -39,7 +40,7 @@ feature is available. ## DevOps Adoption **(ULTIMATE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/alpha-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/experiment-beta-support.md#beta). > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 2ac8941b286..6441cd866c8 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -18,8 +18,9 @@ Prerequisite: To view instance-level analytics: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Analytics**, then one of the available analytics: +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Analytics**, then one of the available analytics: - [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. - [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how the data is changing. diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index a240a1ff524..49e82f71a3a 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -19,8 +19,9 @@ Usage Trends data refreshes daily. To view Usage Trends: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Analytics > Usage Trends**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Analytics > Usage Trends**. ## Total counts diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index a5311b083c3..99c2a453b07 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -9,12 +9,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w Several options are available for customizing the appearance of a self-managed instance of GitLab. To access these settings: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Appearance**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Appearance**. -## Top bar +## Navigation bar -By default, the **top bar** has the GitLab logo, but this can be customized with +By default, the navigation bar has the GitLab logo, but this can be customized with any image desired. It is optimized for images 28px high (any width), but any image can be used (less than 1 MB) and it is automatically resized. @@ -82,8 +83,9 @@ description, and icon. To configure the PWA settings: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Appearance**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Appearance**. 1. Scroll to the **Progressive Web App (PWA)** section. 1. Complete the fields. - **Icon**: If you use the standard GitLab icon, it is available in sizes 192x192 pixels, diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index acb3e92fff8..6fe82b3ae83 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -19,7 +19,7 @@ Broadcast messages can be managed using the [broadcast messages API](../../api/b ## Banners -Banners are shown on the top of a page and in Git remote responses. +Banners are shown on the top of a page and optionally in the command line as a Git remote response. ![Broadcast Message Banner](img/broadcast_messages_banner_v15_0.png) @@ -32,7 +32,7 @@ remote: ... ``` -If more than one banner is active at one time, they are displayed in a stack in order of creation. +If more than one banner is active at one time, they are displayed at the top of the page in order of creation. In the command line, only the latest banner is shown. ## Notifications @@ -57,8 +57,9 @@ To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Messages**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Messages**. 1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: - `color` @@ -69,6 +70,7 @@ To add a broadcast message: - `text-decoration` 1. Select a **Theme**. The default theme is `indigo`. 1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. +1. Optional. Clear the **Git remote responses** checkbox to prevent broadcast messages from being displayed in the command line as Git remote responses. 1. Optional. Select **Target roles** to only show the broadcast message to users with the selected roles. The message displays on group, subgroup, and project pages, and does not display in Git remote responses. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. 1. Select a date and time (UTC) for the message to start and end. @@ -83,8 +85,9 @@ If you must make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Messages**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Messages**. 1. From the list of broadcast messages, select the edit button for the message. 1. After making the required changes, select **Update broadcast message**. @@ -97,8 +100,9 @@ You can delete a broadcast message while it's active. To delete a broadcast message: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Messages**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Messages**. 1. From the list of broadcast messages, select the delete button for the message. When a broadcast message is deleted, it's removed from the list of broadcast messages. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 5fee0c42a77..9bacd101c48 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -31,8 +31,9 @@ You can also [revoke](#revoke-a-users-personal-access-token) and [delete](#delet To access the Credentials inventory: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Credentials**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Credentials**. ## Revoke a user's personal access token diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 9d360539595..0e0acf4af57 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -33,7 +33,9 @@ To set project templates at the group level, see [Custom group-level project tem To select the group to use as the source for the project templates: -1. On the top bar, navigate to **Main menu > Admin > Settings > Templates**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Templates**. 1. Expand **Custom project templates**. 1. Select a group to use. 1. Select **Save changes**. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 3d7c49c1f2b..72e8269e455 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -33,8 +33,9 @@ set values are presented as **Too large** are cannot be expanded in the UI. To configure these values: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for the diff limit. 1. Select **Save changes**. diff --git a/doc/user/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md index ba465fbea29..fbdfe437719 100644 --- a/doc/user/admin_area/email_from_gitlab.md +++ b/doc/user/admin_area/email_from_gitlab.md @@ -22,8 +22,9 @@ For information about email notifications originating from GitLab, read ## Sending emails to users from GitLab -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select **Send email to users**. ![administrators](img/email1.png) diff --git a/doc/user/admin_area/external_users.md b/doc/user/admin_area/external_users.md index 5127630d65e..a63093deab0 100644 --- a/doc/user/admin_area/external_users.md +++ b/doc/user/admin_area/external_users.md @@ -40,7 +40,8 @@ An administrator can flag a user as external by either of the following methods: - [Through the API](../../api/users.md#user-modification). - Using the GitLab UI: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. @@ -55,8 +56,9 @@ Additionally, users can be set as external users using: By default, new users are not set as external users. This behavior can be changed by an administrator: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Account and limit** section. If you change the default behavior of creating new users as external, you diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md index 9fe36188dd0..3bae90aaec8 100644 --- a/doc/user/admin_area/geo_sites.md +++ b/doc/user/admin_area/geo_sites.md @@ -11,8 +11,9 @@ You can configure various settings for GitLab Geo sites. For more information, s On either the primary or secondary site: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Geo > Sites**. ## Common settings @@ -71,8 +72,9 @@ the primary uses the secondary's internal URL to contact it directly. The internal URL defaults to external URL. To change it: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** on the site you want to customize. 1. Edit the internal URL. 1. Select **Save changes**. diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 71c2468c97f..a59501f14ce 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -7,72 +7,24 @@ type: reference # GitLab Admin Area **(FREE SELF)** -The Admin Area provides a web UI to manage and configure some features of GitLab -self-managed instances. If you are an administrator, you can access the Admin Area -by visiting `/admin` on your self-managed instance. You can also access it through -the UI: +The Admin Area provides a web UI to manage and configure features of GitLab +self-managed instances. If you are an administrator,to access the Admin Area: -- GitLab versions 14.0 and later: on the top bar, select **Main menu > Admin**. -- GitLab versions 13.12 and earlier: on the top bar, select the Admin Area icon (**{admin}**). +- In GitLab 16.1 and later: on the left sidebar, expand the top-most chevron (**{chevron-down}**), then select **Admin Area**. +- In GitLab 16.0 and earlier: on the top bar, select **Main menu > Admin**. NOTE: Only administrators can access the Admin Area. -## Admin Area sections - -The Admin Area is made up of the following sections: - -| Section | Description | -|:-----------------------------------------------|:------------| -| **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-area-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [topics](#administering-topics), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | -| **{monitor}** Monitoring | View GitLab [system information](#system-information), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), and [audit events](#audit-events). | -| **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | -| **{hook}** System Hooks | Configure [system hooks](../../administration/system_hooks.md) for many events. | -| **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | -| **{slight-frown}** Abuse Reports | Manage [abuse reports](review_abuse_reports.md) submitted by your users. | -| **{license}** License | Add, display, and remove [licenses](license.md). | -| **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | -| **{push-rules}** Push rules | Configure pre-defined Git [push rules](../project/repository/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). | -| **{location-dot}** Geo | Configure and maintain [Geo sites](geo_sites.md). | -| **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../project/deploy_keys/index.md). | -| **{lock}** Credentials | View [credentials](credentials_inventory.md) that can be used to access your instance. | -| **{template}** Integrations | Manage [instance-level default settings](settings/project_integration_management.md) for a project integration. | -| **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. | -| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | -| **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | - -## Admin Area dashboard - -The Dashboard provides statistics and system information about the GitLab instance. - -To access the Dashboard, either: - -- On the top bar, select **Main menu > Admin**. -- Visit `/admin` on your self-managed instance. - -The Dashboard is the default view of the Admin Area, and is made up of the following sections: - -| Section | Description | -|:-----------|:------------| -| Projects | The total number of projects, up to 10 of the latest projects, and the option of creating a new project. | -| Users | The total number of users, up to 10 of the latest users, the option of creating a new user, and a link to [**Users statistics**](#users-statistics). | -| Groups | The total number of groups, up to 10 of the latest groups, and the option of creating a new group. | -| Statistics | Totals of all elements of the GitLab instance. | -| Features | All features available on the GitLab instance. Enabled features are marked with a green circle icon, and disabled features are marked with a power icon. | -| Components | The major components of GitLab and the version number of each. A link to the Gitaly Servers is also included. | - -## Overview section - -The following topics document the **Overview** section of the Admin Area. - -### Administering Projects +## Administering projects You can administer all projects in the GitLab instance from the Admin Area's Projects page. To access the Projects page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Projects**. 1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that criteria. @@ -118,12 +70,13 @@ You can combine the filter options. For example, to list only public projects wi 1. Select the **Public** tab. 1. Enter `score` in the **Filter by name...** input box. -### Administering Users +## Administering users You can administer all users in the GitLab instance from the Admin Area's Users page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. To list users matching a specific criteria, select one of the following tabs on the **Users** page: @@ -159,14 +112,15 @@ To search for users, enter your criteria in the search field. The user search is insensitive, and applies partial matching to name and username. To search for an email address, you must provide the complete email address. -#### User impersonation +### User impersonation An administrator can "impersonate" any other user, including other administrators. This allows the administrator to "see what the user sees," and take actions on behalf of the user. You can impersonate a user in the following ways: - Through the UI: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. @@ -178,21 +132,22 @@ By default, impersonation is enabled. GitLab can be configured to [disable imper ![user impersonation button](img/impersonate_user_button_v13_8.png) -#### User identities +### User identities > The ability to see a user's SCIM identity was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294608) in GitLab 15.3. When using authentication providers, administrators can see the identities for a user: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Identities**. This list shows the user's identities, including SCIM identities. Administrators can use this information to troubleshoot SCIM-related issues and confirm the identities being used for an account. -#### User Permission Export **(PREMIUM SELF)** +### User Permission Export **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292436) in GitLab 13.9. @@ -213,7 +168,7 @@ Only the first 100,000 user accounts are exported. ![user permission export button](img/export_permissions_v13_11.png) -#### Users statistics +### Users statistics The **Users statistics** page provides an overview of user accounts by role. These statistics are calculated daily, so user changes made since the last update are not reflected. @@ -226,28 +181,30 @@ The following totals are also included: GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). -#### Add email to user +### Add email to user You must be an administrator to manually add emails to users: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Locate the user and select them. 1. Select **Edit**. 1. In **Email**, enter the new email address. This adds the new email address to the user and sets the previous email address to be a secondary. 1. Select **Save changes**. -### User cohorts +## User cohorts The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and their activities over time. -### Prevent a user from creating groups +## Prevent a user from creating groups By default, users can create groups. To prevent a user from creating a top level group: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Locate the user and select them. 1. Select **Edit**. 1. Clear the **Can create group** checkbox. @@ -255,14 +212,15 @@ By default, users can create groups. To prevent a user from creating a top level It is also possible to [limit which roles can create a subgroup within a group](../group/subgroups/index.md#change-who-can-create-subgroups). -### Administering Groups +## Administering groups You can administer all groups in the GitLab instance from the Admin Area's Groups page. To access the Groups page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Groups**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, number of members, and whether the group is private, internal, or public. To edit a group, in the group's row, select **Edit**. To delete the group, in the group's row, select **Delete**. @@ -273,9 +231,9 @@ sort order is by **Last created**. To search for groups by name, enter your criteria in the search field. The group search is case insensitive, and applies partial matching. -To [Create a new group](../group/manage.md#create-a-group) select **New group**. +To [Create a new group](../group/index.md#create-a-group) select **New group**. -### Administering Topics +## Administering topics - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. - > Merging topics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366884) in GitLab 15.5. @@ -286,8 +244,9 @@ You can administer all topics in the GitLab instance from the Admin Area's Topic To access the Topics page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Topics**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Topics**. For each topic, the page displays its name and the number of projects labeled with the topic. @@ -307,15 +266,16 @@ The assigned topics are visible only to everyone 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. -### Administering Gitaly servers +## Administering Gitaly servers You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** page. For more details, see [Gitaly](../../administration/gitaly/index.md). To access the **Gitaly Servers** page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Gitaly Servers**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: @@ -338,8 +298,9 @@ You can administer all runners in the GitLab instance from the Admin Area's **Ru To access the **Runners** page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Runners**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Runners**. #### Search and filter runners @@ -364,8 +325,9 @@ You can also filter runners by status, type, and tag. To filter: You can delete multiple runners at the same time. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Runners**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Runners**. 1. To the left of the runners you want to delete, select the checkbox. To select all of the runners on the page, select the checkbox above the list. @@ -394,8 +356,9 @@ You can administer all jobs in the GitLab instance from the Admin Area's Jobs pa To access the Jobs page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **CI/CD > Jobs**. All jobs are listed, in descending order of job ID. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **CI/CD > Jobs**. All jobs are listed, in descending order of job ID. 1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 823f876539f..be6478de2a0 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -28,8 +28,9 @@ To activate your instance with an activation code: - Your subscription confirmation email. - The [Customers Portal](https://customers.gitlab.com/customers/sign_in), on the **Manage Purchases** page. 1. Sign in to your GitLab self-managed instance. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Subscription**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Subscription**. 1. Paste the activation code in **Activation code**. 1. Read and accept the terms of service. 1. Select **Activate**. diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index 01d2c31dd10..12e908b4fe0 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -18,8 +18,9 @@ link to the **Add license** page should be displayed. Otherwise, to add your license: 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. In the **Add License** area, add a license by either uploading the file or entering the key. 1. Select the **Terms of Service** checkbox. 1. Select **Add license**. @@ -42,7 +43,7 @@ export GITLAB_ACTIVATION_CODE=your_activation_code If you have a license, you can also import it when you install GitLab. -- **For installations from source** +- For self-compiled installations: - Place the `Gitlab.gitlab-license` file in the `config/` directory. - To specify a custom location and filename for the license, set the `GITLAB_LICENSE_FILE` environment variable with the path to the file: @@ -51,7 +52,7 @@ If you have a license, you can also import it when you install GitLab. export GITLAB_LICENSE_FILE="/path/to/license/file" ``` -- **For Omnibus package** +- For Linux package installations: - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: @@ -95,8 +96,9 @@ To go back to Free features, [delete all expired licenses](#remove-a-license). To remove a license from a self-managed instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Subscription**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Subscription**. 1. Select **Remove license**. Repeat these steps to remove all licenses, including those applied in the past. @@ -105,8 +107,9 @@ Repeat these steps to remove all licenses, including those applied in the past. To view your license details: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Subscription**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Subscription**. You can add and view more than one license, but only the latest license in the current date range is the active license. diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index b2f24091d7c..58f54c399df 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -19,8 +19,10 @@ and can no longer be changed: To enable merge request approval settings for an instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request approvals**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Push Rules**. +1. Expand **Merge request approvals**. 1. Choose the required options. 1. Select **Save changes**. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index b0e24559e47..ee6d360ac1d 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -42,8 +42,9 @@ sign in. To view user sign ups pending approval: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Pending approval** tab. ### Approve or reject a user sign up @@ -52,8 +53,9 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Pending approval** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. @@ -77,8 +79,9 @@ administrators can choose to block the user. Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), by removing them in LDAP, or directly from the Admin Area. To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. 1. Select **Block**. @@ -100,8 +103,9 @@ Users can also be blocked using the [GitLab API](../../api/users.md#block-user). A blocked user can be unblocked from the Admin Area. To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Blocked** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. @@ -116,8 +120,9 @@ Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-us The unblock option may be unavailable for LDAP users. To enable the unblock option, the LDAP identity first needs to be deleted: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Blocked** tab. 1. Select a user. 1. Select the **Identities** tab. @@ -155,8 +160,9 @@ Users are notified about account deactivation if A user can be deactivated from the Admin Area. To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. 1. Select **Deactivate**. @@ -182,8 +188,9 @@ Administrators can enable automatic deactivation of users who either: To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Under **Dormant users**, check **Deactivate dormant users after a period of inactivity**. 1. Under **Days of inactivity before deactivation**, enter the number of days before deactivation. Minimum value is 90 days. @@ -201,8 +208,9 @@ A deactivated user can be activated from the Admin Area. To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Deactivated** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. @@ -218,14 +226,11 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u ## Ban and unban users > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ban_user_feature_flag`. Disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/330667) in GitLab 14.8. +> - Ban and unban users [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.8. Feature flag `ban_user_feature_flag` removed. +> - Hiding merge requests of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107836) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `hide_merge_requests_from_banned_users`. Disabled by default. +> - Hiding comments of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112973) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `hidden_notes`. Disabled by default. -FLAG: -On self-managed GitLab, by default this feature is available. -On GitLab.com, this feature is available to GitLab.com administrators only. - -GitLab administrators can ban and unban users. Banned users are blocked, and their issues and merge requests are hidden. -The banned user's comments are still displayed. Hiding a banned user's comments is [tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327356). +GitLab administrators can ban and unban users. Banned users are blocked, and their issues, merge requests, and comments are hidden. ### Ban a user @@ -233,8 +238,9 @@ To block a user and hide their contributions, administrators can ban the user. Users can be banned using the Admin Area. To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. 1. Select **Ban user**. @@ -245,8 +251,9 @@ The banned user does not consume a [seat](../../subscriptions/self_managed/index A banned user can be unbanned using the Admin Area. To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Banned** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. @@ -259,8 +266,9 @@ The user's state is set to active and they consume a Use the Admin Area to delete users. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Banned** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. @@ -273,8 +281,9 @@ You can only delete a user if there are inherited or direct owners of a group. Y You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Banned** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown list. diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index 83b28404714..38aaeb8eb55 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Git abuse rate limit (administration) **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/394996) in GitLab 15.10. Feature flag `git_abuse_rate_limit_feature_flag` removed. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/394996) in GitLab 15.11. Feature flag `git_abuse_rate_limit_feature_flag` removed. This is the administration documentation. For information about Git abuse rate limiting at the group level, see the [group-level documentation](../../group/reporting/git_abuse_rate_limit.md). @@ -15,10 +15,15 @@ Git abuse rate limiting is a feature to automatically [ban users](../moderate_us Git abuse rate limiting does not apply to instance administrators, [deploy tokens](../../../user/project/deploy_tokens/index.md), or [deploy keys](../../../user/project/deploy_keys/index.md). +How GitLab determines a user's rate limit is under development. +GitLab team members can view more information in this confidential epic: +`https://gitlab.com/groups/gitlab-org/modelops/anti-abuse/-/epics/14`. + ## Configure Git abuse rate limiting -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Reporting**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Reporting**. 1. Expand **Git abuse rate limit**. 1. Update the Git abuse rate limit settings: 1. Enter a number in the **Number of repositories** field, greater than or equal to `0` and less than or equal to `10,000`. This number specifies the maximum amount of unique repositories a user can download in the specified time period before they're banned. When set to `0`, Git abuse rate limiting is disabled. @@ -36,8 +41,9 @@ If automatic banning is enabled, an email notification is sent when a user is ab ## Unban a user -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Banned** tab and search for the account you want to unban. 1. From the **User administration** dropdown list select **Unban user**. 1. On the confirmation dialog, select **Unban user**. diff --git a/doc/user/admin_area/reporting/ip_addr_restrictions.md b/doc/user/admin_area/reporting/ip_addr_restrictions.md new file mode 100644 index 00000000000..5b749c62c30 --- /dev/null +++ b/doc/user/admin_area/reporting/ip_addr_restrictions.md @@ -0,0 +1,33 @@ +--- +stage: Anti-Abuse +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 +--- + +# IP address restrictions **(FREE SELF)** + +IP address restrictions help prevent malicious users hiding their activities behind multiple IP addresses. + +GitLab maintains a list of the unique IP addresses used by a user to make requests over a specified period. When the +specified limit is reached, any requests made by the user from a new IP address are rejected with a `403 Forbidden` error. + +IP addresses are cleared from the list when no further requests have been made by the user from the IP address in the specified time period. + +NOTE: +When a runner runs a CI/CD job as a particular user, the runner IP address is also stored against the user's list of +unique IP addresses. Therefore, the IP addresses per user limit should take into account the number of configured active runners. + +## Configure IP address restrictions + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Reporting**. +1. Expand **Spam and Anti-bot Protection**. +1. Update the IP address restrictions settings: + 1. Select the **Limit sign in from multiple IP addresses** checkbox to enable IP address restrictions. + 1. Enter a number in the **IP addresses per user** field, greater than or equal to `1`. This number specifies the + maximum number of unique IP addresses a user can access GitLab from in the specified time period before requests + from a new IP address are rejected. + 1. Enter a number in the **IP address expiration time** field, greater than or equal to `0`. This number specifies the + time in seconds an IP address counts towards the limit for a user, taken from the time the last request was made. +1. Select **Save changes**. diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md index 16c144d2469..e2508476c80 100644 --- a/doc/user/admin_area/reporting/spamcheck.md +++ b/doc/user/admin_area/reporting/spamcheck.md @@ -40,8 +40,9 @@ Spamcheck is only available for package-based installations: ## Configure GitLab to use Spamcheck -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Reporting**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Update the Spam Check settings: 1. Check the "Enable Spam Check via external API endpoint" checkbox. diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 314e0c77f36..5cd63ec964c 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -16,8 +16,9 @@ reports in the Admin Area. To receive notifications of new abuse reports by email: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Reporting**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address and select **Save changes**. @@ -33,8 +34,9 @@ To find out more about reporting abuse, see To access abuse reports: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Abuse Reports**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Abuse Reports**. There are 3 ways to resolve an abuse report, with a button for each method: diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 5c730375f98..293decc438e 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -16,8 +16,10 @@ the [project limits for existing users](#projects-limit-for-a-user). To configure the maximum number of projects in personal namespaces for new users: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Increase or decrease that **Default projects limit** value. If you set **Default projects limit** to 0, users are not allowed to create projects @@ -28,8 +30,9 @@ in their users personal namespace. However, projects can still be created in a g You can edit a specific user, and change the maximum number of projects this user can create in their personal namespace: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview** > **Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview** > **Users**. 1. From the list of users, select a user. 1. Select **Edit**. 1. Increase or decrease the **Projects limit** value. @@ -41,8 +44,10 @@ can create in their personal namespace: The maximum file size for attachments in GitLab comments and replies is 100 MB. To change the maximum attachment size: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. If you choose a size larger than the configured value for the web server, @@ -55,8 +60,10 @@ For GitLab.com repository size limits, read [accounts and limit settings](../../ You can change the maximum push size for your instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum push size (MB)**. For GitLab.com push size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). @@ -74,8 +81,9 @@ Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a reposito To modify the maximum file size for exports in GitLab: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum export size (MB)**. ## Max import size @@ -84,8 +92,10 @@ To modify the maximum file size for exports in GitLab: To modify the maximum file size for imports in GitLab: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum import size (MB)**. This setting applies only to repositories @@ -114,8 +124,9 @@ The default prefix is `glpat-` but administrators can change it. To change the default global prefix: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Personal Access Token prefix** field. 1. Select **Save changes**. @@ -160,8 +171,9 @@ These settings can be found in: 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Select **Save changes**. - GitLab global settings: - 1. On the top bar, select **Main menu > Admin**. - 1. On the left sidebar, select **Settings > General**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MB)** field. 1. Select **Save changes**. @@ -182,8 +194,9 @@ For details on manually purging files, see [reducing the repository size using G You can change how long users can remain signed in without activity. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Account and limit**. The set duration is in **Session duration (minutes)**. If [Remember me](#turn-remember-me-on-or-off) is enabled, users' sessions can remain active for an indefinite period of time. @@ -196,8 +209,9 @@ For details, see [cookies used for sign-in](../../profile/index.md#cookies-used- Users can select the **Remember me** checkbox on sign-in, and their session will remain active for an indefinite period of time when accessed from that specific browser. You can turn off this setting if you need sessions to expire for security or compliance purposes. Turning off this setting will ensure users' sessions expire after the number of minutes of inactivity set when you [customize your session duration](#customize-the-default-session-duration). -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select or clear the **Remember me** checkbox to turn this setting on or off. @@ -213,8 +227,9 @@ GitLab administrators can choose to customize the session duration (in minutes) To set a limit on how long these sessions are valid: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. 1. Select **Save changes**. @@ -240,8 +255,9 @@ there are no restrictions. To set a lifetime on how long SSH keys are valid: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for SSH keys (days)** field. 1. Select **Save changes**. @@ -276,8 +292,9 @@ there are no restrictions. To set a lifetime on how long access tokens are valid: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for access tokens (days)** field. 1. Select **Save changes**. @@ -298,8 +315,10 @@ To maintain integrity of user details in [Audit Events](../../../administration/ To do this: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Select the **Prevent users from changing their profile name** checkbox. NOTE: @@ -318,8 +337,10 @@ By default, new users can create top-level groups. GitLab administrators can pre - The [application setting API](../../../api/settings.md#change-application-settings). - In GitLab 15.4 and earlier, a [configuration file](../../../administration/user_settings.md#use-configuration-files-to-prevent-new-users-from-creating-top-level-groups). -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Clear the **Allow new users to create top-level groups** checkbox. ## Set profiles of new users to private by default @@ -328,19 +349,23 @@ By default, new users can create top-level groups. GitLab administrators can pre By default, newly created users have a public profile. GitLab administrators can set new users to have a private profile by default: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Select the **Make new users' profiles private by default** checkbox. ## Prevent users from deleting their accounts **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26053) in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `deleting_account_disabled_for_users`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26053) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `deleting_account_disabled_for_users`. Enabled by default. By default, users can delete their own accounts. GitLab administrators can prevent users from deleting their own accounts: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Account and limit**. 1. Clear the **Allows users to delete their own accounts** checkbox. ## Troubleshooting @@ -352,7 +377,7 @@ error, the [max attachment size](#max-attachment-size) is probably larger than the web server's allowed value. To increase the max attachment size to 200 MB in a -[Omnibus GitLab](https://docs.gitlab.com/omnibus/) install, you may need to +[Linux package](https://docs.gitlab.com/omnibus/) install, you may need to add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachment size: ```ruby diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 27af64cd0e8..853a299cdec 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -15,8 +15,9 @@ job artifacts. To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. 1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/requirements.md#auto-devops-base-domain) which is used for Auto Deploy and Auto Review Apps. @@ -32,17 +33,18 @@ If you want to disable it for a specific project, you can do so in You can set all new projects to have the instance's shared runners available by default. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Select the **Enable shared runners for new projects** checkbox. Any time a new project is created, the shared runners are available. -## Shared runners CI/CD minutes +## Shared runners compute quota As an administrator you can set either a global or namespace-specific -limit on the number of [CI/CD minutes](../../../ci/pipelines/cicd_minutes.md) you can use. +limit on the number of [units of compute](../../../ci/pipelines/cicd_minutes.md) you can use. ## Enable a project runner for multiple projects @@ -51,7 +53,8 @@ you can assign that runner to other projects. To enable a project runner for more than one project: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. 1. In the upper-right corner, select **Edit** (**{pencil}**). @@ -64,8 +67,9 @@ To enable a project runner for more than one project: To display details about the instance's shared runners in all projects' runner settings: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Enter text, including Markdown if you want, in the **Shared runner details** field. For example: @@ -73,10 +77,8 @@ runner settings: To view the rendered details: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Settings > CI/CD**. 1. Expand **Runners**. ![Shared runner details example](img/continuous_integration_shared_runner_details_v14_10.png) @@ -95,7 +97,8 @@ The value is in MB and the default is 100 MB per job. To change it at the: - Instance level: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > CI/CD > Continuous Integration and Deployment**. 1. Change the value of **Maximum artifacts size (MB)**. 1. Select **Save changes** for the changes to take effect. @@ -122,8 +125,9 @@ can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) and the default value is `30 days`. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Select **Save changes** for the changes to take effect. @@ -153,8 +157,9 @@ If disabled at the instance level, you cannot enable this per-project. To disable the setting: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. 1. Select **Save changes** @@ -173,8 +178,9 @@ but persisting the traces and artifacts for auditing purposes. To set the duration for which the jobs are considered as old and expired: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. 1. Select **Save changes** for the changes to take effect. @@ -190,17 +196,21 @@ For the value set for GitLab.com, see [Scheduled job archiving](../../gitlab_com To set all new [CI/CD variables](../../../ci/variables/index.md) as [protected](../../../ci/variables/index.md#protect-a-cicd-variable) by default: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Select **Protect CI/CD variables by default**. ## Maximum includes +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207270) in GitLab 16.0. + The maximum number of [includes](../../../ci/yaml/includes.md) per pipeline can be set at the instance level. The default is `150`. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Change the value of **Maximum includes**. 1. Select **Save changes** for the changes to take effect. @@ -211,8 +221,9 @@ The default is `150`. The default CI/CD configuration file and path for new projects can be set in the Admin Area of your GitLab instance (`.gitlab-ci.yml` if not set): -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Input the new file and path in the **Default CI/CD configuration file** field. 1. Select **Save changes** for the changes to take effect. @@ -225,8 +236,9 @@ It is also possible to specify a [custom CI/CD configuration file for a specific You can configure some [CI/CD limits](../../../administration/instance_limits.md#cicd-limits) from the Admin Area: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. In the **CI/CD limits** section, you can set the following limits: - **Maximum number of jobs in a single pipeline** @@ -248,8 +260,9 @@ walkthrough on how to add one. To enable or disable the banner: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Select or clear the **Enable pipeline suggestion banner** checkbox. 1. Select **Save changes**. @@ -284,8 +297,9 @@ in the pipeline editor. To select a CI/CD template for the required pipeline configuration: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select a CI/CD template from the dropdown list. 1. Select **Save changes**. @@ -298,8 +312,9 @@ GitLab administrators can disable the forwarding of Maven requests to [Maven Cen To disable forwarding Maven requests: -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward Maven package requests to the Maven Registry if the packages are not found in the GitLab Package Registry**. 1. Select **Save changes**. @@ -310,8 +325,9 @@ GitLab administrators can disable the forwarding of npm requests to [npmjs.com]( To disable it: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. 1. Select **Save changes**. @@ -322,8 +338,9 @@ GitLab administrators can disable the forwarding of PyPI requests to [pypi.org]( To disable it: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. 1. Select **Save changes**. @@ -334,8 +351,9 @@ GitLab administrators can adjust the maximum allowed file size for each package To set the maximum file size: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. 1. Enter the maximum file size, in bytes. @@ -354,8 +372,9 @@ By default, all members of a project and group are able to register runners. To restrict all users in an instance from registering runners: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Runner registration** section, clear the **Members of the project can register runners** and **Members of the group can register runners** checkboxes to remove runner registration from the UI. @@ -376,8 +395,9 @@ GitLab administrators can adjust group permissions to restrict runner registrati To restrict runner registration by members in a specific group: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Groups** and find your group. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Groups** and find your group. 1. Select **Edit**. 1. Clear the **New group runners can be registered** checkbox if you want to disable runner registration by all members in the group. If the setting is read-only, you must enable runner registration for the [instance](#restrict-runner-registration-by-all-users-in-an-instance). 1. Select **Save changes**. @@ -390,8 +410,9 @@ By default, GitLab instances periodically fetch official runner version data fro To disable your instance fetching this data: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Runner version management** section, clear the **Fetch GitLab Runner release version data from GitLab.com** checkbox. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md index 13f8bc008e3..e813d8fe2b1 100644 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ b/doc/user/admin_area/settings/deprecated_api_rate_limits.md @@ -34,8 +34,9 @@ Prerequisite: To override the general user and IP rate limits for requests to deprecated API endpoints: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Deprecated API Rate Limits**. 1. Select the checkboxes for the types of rate limits you want to enable: - **Unauthenticated API request rate limit** diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 90852463e9d..1caa1728ea4 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -11,7 +11,7 @@ You can customize some of the content in emails sent from your GitLab instance. ## Custom logo -The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#top-bar). +The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). ## Include author name in email notification email body **(PREMIUM SELF)** @@ -21,8 +21,9 @@ address in the body of the email instead. To include the author's email address in the email body: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Select the **Include author name in email notification email body** checkbox. 1. Select **Save changes**. @@ -33,8 +34,9 @@ GitLab can send email in multipart format (HTML and plain text) or plain text on To enable multipart email: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Select **Enable multipart email**. 1. Select **Save changes**. @@ -48,8 +50,9 @@ This configuration option sets the email hostname for [private commit emails](.. To change the hostname used in private commit emails: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. 1. Select **Save changes**. @@ -66,8 +69,9 @@ can be used for legal, auditing, or compliance reasons, for example. To add additional text to emails: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter your text in the **Additional text** field. 1. Select **Save changes**. @@ -78,8 +82,9 @@ GitLab sends email notifications to users when their account has been deactivate To disable these notifications: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Clear the **Enable user deactivation emails** checkbox. 1. Select **Save changes**. @@ -100,8 +105,9 @@ setting. To add additional text to deactivation emails: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter your text in the **Additional text for deactivation email** field. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 072873ba7f6..c15062dd518 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -32,12 +32,12 @@ authorization service. Whenever access is granted or denied this is logged in a log file called `external-policy-access-control.log`. Read more about the logs GitLab keeps in -the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs.html). +the [Linux package documentation](https://docs.gitlab.com/omnibus/settings/logs.html). When using TLS Authentication with a self signed certificate, the CA certificate needs to be trusted by the OpenSSL installation. When using GitLab installed -using Omnibus, learn to install a custom CA in the -[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.html). +using the Linux package, learn to install a custom CA in the +[Linux package documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.html). Alternatively, learn where to install custom certificates by using `openssl version -d`. @@ -45,8 +45,9 @@ Alternatively, learn where to install custom certificates by using The external authorization service can be enabled by an administrator: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **External authorization**. 1. Complete the fields. 1. Select **Save changes**. @@ -65,8 +66,9 @@ Prerequisites: To allow authorization with deploy tokens and keys: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **External authorization**, and: - Leave the service URL field empty. - Select **Allow deploy tokens and deploy keys to be used with external authorization**. diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index 8677e3d86bf..9f7a2d13b8e 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -30,8 +30,9 @@ Prerequisite: To override the general user and IP rate limits for requests to the Repository files API: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Files API Rate Limits**. 1. Select the checkboxes for the types of rate limits you want to enable: - **Unauthenticated API request rate limit** diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 451acc07240..6bd5a6dfed4 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -22,8 +22,9 @@ Permissions-Policy: interest-cohort=() To enable it: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Federated Learning of Cohorts (FLoC)**. 1. Select the **Participate in FLoC** checkbox. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md index e0476f1e333..c9b294417ee 100644 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -21,8 +21,9 @@ rate limits. Git LFS rate limits are disabled by default. If enabled and configured, these limits supersede the [general user and IP rate limits](user_and_ip_rate_limits.md): -1. On the top bar, select **Main menu >** **{admin}** **Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Git LFS Rate Limits**. 1. Select **Enable authenticated Git LFS request rate limit**. 1. Enter a value for **Max authenticated Git LFS requests per period per user**. diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index d18fe0d74cd..d28e9ec0249 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -11,8 +11,9 @@ configured to make sure that long-running Gitaly calls don't needlessly take up To access Gitaly timeout settings: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand the **Gitaly timeouts** section. ## Available timeouts diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 5d9fc23aaff..febd794b04c 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -16,8 +16,9 @@ the GitLab sign-in page. You can add a help message, which is shown at the top of the GitLab `/help` page (for example, <https://gitlab.com/help>): -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. 1. Select **Save changes**. @@ -33,8 +34,9 @@ is restricted, `/help` is visible only to authenticated users. You can add a help message, which is shown on the GitLab sign-in page. The message appears on the sign-in page: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the sign-in page**, enter the information you want to display on the sign-in page. @@ -46,8 +48,9 @@ You can now see the message on the sign-in page. GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. Select the **Hide marketing-related entries from the Help page** checkbox. 1. Select **Save changes**. @@ -59,8 +62,9 @@ You can specify a custom URL to which users are directed when they: - Select **Support** from the Help dropdown list. - Select **See our website for help** on the Help page. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Support page URL** field, enter the URL. 1. Select **Save changes**. @@ -73,8 +77,9 @@ You can specify a custom URL to which users are directed when they: You can redirect all `/help` links to a destination that meets the [necessary requirements](#destination-requirements). -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Documentation pages URL** field, enter the URL. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index 36a8b340957..99385c77cdf 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -12,8 +12,10 @@ You can configure the rate limits for imports and exports of projects and groups To change a rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, then expand **Import and export rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Import and export rate limits**. 1. Change the value of any rate limit. The rate limits are per minute per user, not per IP address. Set to `0` to disable a rate limit. diff --git a/doc/user/admin_area/settings/incident_management_rate_limits.md b/doc/user/admin_area/settings/incident_management_rate_limits.md index 295569dafee..0b6e572837e 100644 --- a/doc/user/admin_area/settings/incident_management_rate_limits.md +++ b/doc/user/admin_area/settings/incident_management_rate_limits.md @@ -30,8 +30,9 @@ Requests that exceed the limit are logged into `auth.log`. To set inbound incident management alert limits: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Incident Management Limits**. 1. Select the **Enable Incident Management inbound alert limit** checkbox. 1. Optional. Input a custom value for **Maximum requests per project per rate limit period**. Default is 3600. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 2091191b889..632adf273c4 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -19,8 +19,9 @@ read [GitLab.com settings](../../gitlab_com/index.md). To access the **Admin Area**: 1. Sign in to your GitLab instance as an administrator. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings**, and the group of settings to view: +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings**, and the group of settings to view: - [General](#general) - [Geo](#geo) - [CI/CD](#cicd) @@ -96,7 +97,7 @@ The **Integrations** settings contain: [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). - [Customer experience improvement and third-party offers](third_party_offers.md) - Control the display of customer experience improvement content and third-party offers. -- [Snowplow](../../../development/snowplow/index.md) - Configure the Snowplow integration. +- [Snowplow](../../../development/internal_analytics/snowplow/index.md) - Configure the Snowplow integration. - [Google GKE](../../project/clusters/add_gke_clusters.md) - Google GKE integration enables you to provision GKE clusters from GitLab. - [Amazon EKS](../../project/clusters/add_eks_clusters.md) - Amazon EKS integration enables @@ -108,7 +109,7 @@ The **Metrics and profiling** settings contain: - [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) - Enable and configure Prometheus metrics. -- [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integration-with-gitlab-ui) - +- [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integrate-with-gitlab-ui) - Enable and configure Grafana. - [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-for-non-administrators) - Enable access to the Performance Bar for non-administrator users in a given group. @@ -161,8 +162,10 @@ The **Preferences** settings contain: The **Reporting** settings contain: -- [Spam and Anti-bot Protection](../../../integration/recaptcha.md) - - Enable anti-spam services, like reCAPTCHA, Akismet, or [Spamcheck](../reporting/spamcheck.md), and set IP limits. +- Spam and Anti-bot protection: + - Anti-spam services, such as [reCAPTCHA](../../../integration/recaptcha.md), + [Akismet](../../../integration/akismet.md), or [Spamcheck](../reporting/spamcheck.md). + - [IP address restrictions](../reporting/ip_addr_restrictions.md). - [Abuse reports](../review_abuse_reports.md) - Set notification email for abuse reports. - [Git abuse rate limit](../reporting/git_abuse_rate_limit.md) - Configure Git abuse rate limit settings. **(ULTIMATE SELF)** @@ -199,8 +202,9 @@ The **Templates** settings contain: You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired first day of the week. ## Default language @@ -208,6 +212,7 @@ for the entire GitLab instance: You can change the [Default language](../../profile/preferences.md) for the entire GitLab instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired default language. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 026782ae83b..a5148c41b74 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -20,8 +20,9 @@ while the project remains secure. To select a project to serve as the custom template repository: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Templates**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown list, select the project to use as the template repository. 1. Select **Save changes**. @@ -43,7 +44,6 @@ are supported: | `.gitignore` | `gitignore` | `.gitignore` | | `.gitlab-ci.yml` | `gitlab-ci` | `.yml` | | `LICENSE` | `LICENSE` | `.txt` | -| `metrics-dashboard.yml` | `metrics-dashboards` | `.yml` | Each template must go in its respective subdirectory, have the correct extension and not be empty. So, the hierarchy should look like this: @@ -62,9 +62,6 @@ extension and not be empty. So, the hierarchy should look like this: |-- LICENSE |-- custom_license.txt |-- another_license.txt -|-- metrics-dashboards - |-- custom_metrics-dashboard.yml - |-- another_metrics-dashboard.yml ``` Your custom templates are displayed on the dropdown list when a new file is added through the GitLab UI: diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md index a5c5536f22d..a1bc339ddd9 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -30,8 +30,10 @@ no difference in functionality compared to the general user and IP rate limits. To enable the unauthenticated request rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **Package registry rate limits**. 1. Select **Enable unauthenticated request rate limit**. - Optional. Update the **Maximum unauthenticated requests per rate limit period per IP** value. @@ -43,8 +45,10 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **Package registry rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network** +1. Expand **Package registry rate limits**. 1. Select **Enable authenticated API request rate limit**. - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index dd4349fca2e..1bb4465020c 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -22,8 +22,9 @@ Only the complete settings for an integration can be inherited. Per-field inheri > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Integrations**. 1. Select an integration. 1. Enter configuration details and select **Save changes**. @@ -54,8 +55,9 @@ integration on all non-configured groups and projects by default. ### Remove an instance-level default setting -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Integrations**. 1. Select an integration. 1. Select **Reset** and confirm. @@ -68,8 +70,9 @@ Resetting an instance-level default setting removes the integration from all pro You can view which projects in your instance use custom settings that [override the instance-level default settings](#use-custom-settings-for-a-group-or-project-integration) for an integration. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Integrations**. 1. Select an integration. 1. Select the **Projects using custom settings** tab. diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 0c3f299e9ec..56a2902f2d9 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -26,11 +26,13 @@ the activity feed. To modify this setting: - In the Admin Area: - 1. On the top bar, select **Main menu > Admin**. - 1. On the left sidebar, select **Settings > Network**, then expand **Performance optimization**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Settings > Network**. + 1. Expand **Performance optimization**. - Through the [Application settings API](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) as `push_event_activities_limit`. -The default value is 3, but it can be greater than or equal 0. +The default value is `3`, but the value can be greater than or equal to `0`. Setting this value to `0` does not disable throttling. ![Push event activities limit](img/push_event_activities_limit_v12_4.png) diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index 547e543ab88..09a1e023c2b 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -12,8 +12,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w This setting allows you to rate limit the requests to the issue and epic creation endpoints. To can change its value: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Issues Rate Limits**. 1. Under **Max requests per minute**, enter the new value. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 8465dccdbf3..59548836e78 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -13,8 +13,9 @@ You can configure the per-user rate limit for requests to the note creation endp To change the note creation rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Notes rate limit**. 1. In the **Maximum requests per minute** box, enter the new value. 1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. diff --git a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md index 152ef535ff8..2d0c4405211 100644 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md @@ -26,8 +26,9 @@ Requests that exceed the limit are logged in the `application_json.log` file. To limit the number of pipeline requests: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Pipelines Rate Limits**. 1. Under **Max requests per minute**, enter a value greater than `0`. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/rate_limit_on_projects_api.md b/doc/user/admin_area/settings/rate_limit_on_projects_api.md index 29e72daf579..326dd3b4706 100644 --- a/doc/user/admin_area/settings/rate_limit_on_projects_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_projects_api.md @@ -16,8 +16,9 @@ You can configure the rate limit per IP address for unauthenticated requests to To change the rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Projects API rate limit**. 1. In the **Maximum requests per 10 minutes per IP address** text box, enter the new value. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md index f61c381a4fb..112518131bf 100644 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_users_api.md @@ -13,8 +13,9 @@ You can configure the per user rate limit for requests to [Users API](../../../a To change the rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Users API rate limit**. 1. In the **Maximum requests per 10 minutes** text box, enter the new value. 1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 7e262c45f48..78e65f7ba7b 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -11,8 +11,9 @@ type: reference This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Performance optimization**. For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute. diff --git a/doc/user/admin_area/settings/scim_setup.md b/doc/user/admin_area/settings/scim_setup.md index fd6e3061140..0471dffe442 100644 --- a/doc/user/admin_area/settings/scim_setup.md +++ b/doc/user/admin_area/settings/scim_setup.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically: - Create users. -- Remove users (deactivate SCIM identity). +- Block users. The [internal GitLab SCIM API](../../../development/internal_api/index.md#instance-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). @@ -26,9 +26,18 @@ Prerequisites: To configure GitLab SCIM: -1. On the top bar, select **Main menu > Admin area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **SCIM Token** section and select **Generate a SCIM token**. 1. For configuration of your identity provider, save the: - Token from the **Your SCIM token** field. - URL from the **SCIM API endpoint URL** field. + +## Remove access + +Removing or deactivating a user on the identity provider blocks the user on +the GitLab instance, while the SCIM identity remains linked to the GitLab user. + +To update the user SCIM identity, use the +[internal GitLab SCIM API](../../../development/internal_api/index.md#update-a-single-scim-provisioned-user-1). diff --git a/doc/user/admin_area/settings/security_and_compliance.md b/doc/user/admin_area/settings/security_and_compliance.md index c7f4d6a3ede..54fd04f6521 100644 --- a/doc/user/admin_area/settings/security_and_compliance.md +++ b/doc/user/admin_area/settings/security_and_compliance.md @@ -17,8 +17,9 @@ We are actively working on reducing this data size in [epic 10415](https://gitla To choose the packages you want to synchronize with the GitLab License Database for [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/index.md): -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Security and Compliance**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Security and Compliance**. 1. Expand **License Compliance**. 1. Select or clear checkboxes for the package registries that you want to sync. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md index a25bc0e85e4..08c3ced4c4e 100644 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ b/doc/user/admin_area/settings/sidekiq_job_limits.md @@ -17,8 +17,9 @@ Redis. To avoid excessive memory for Redis, we: To access Sidekiq job size limits: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Sidekiq job size limits**. 1. Adjust the compression threshold or size limit. The compression can be disabled by selecting the **Track** mode. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 951e0784c88..3b79e55f998 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -12,8 +12,9 @@ You can use **Sign-in restrictions** to customize authentication restrictions fo To access sign-in restriction settings: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Sign-in restrictions** section. ## Password authentication enabled @@ -32,13 +33,13 @@ In the event of an external authentication provider outage, use the [GitLab Rail > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. -If you are an administrator, you might want to work in GitLab without the access that -comes from being an administrator. While you could create a separate user account that -doesn't have administrator access, a more secure solution is to use *Admin Mode*. +If you're an administrator, you might want to work in GitLab without administrator access. +You could either create a separate user account that does not have +administrator access or use Admin Mode. -With Admin Mode, your account does not have administrative access by default. -You can continue to access groups and projects you are a member of, but to access -administrative functionality, you must authenticate. +With Admin Mode, your account does not have administrator access by default. +You can continue to access groups and projects you're a member of. However, for administrative tasks, +you must authenticate (except for [certain features](#limitations-of-admin-mode)). When Admin Mode is enabled, it applies to all administrators on the instance. @@ -75,8 +76,9 @@ Open the [Rails console](../../../administration/operations/rails_console.md) an To enable Admin Mode through the UI: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-in restrictions**. 1. In the **Admin Mode** section, select the **Require additional authentication for administrative tasks** checkbox. @@ -84,7 +86,8 @@ To enable Admin Mode through the UI: To turn on Admin Mode for your current session and access potentially dangerous resources: -1. On the top bar, select **Main menu > Enter Admin Mode**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Enter Admin Mode**. 1. Try to access any part of the UI with `/admin` in the URL (which requires administrator access). When Admin Mode status is disabled or turned off, administrators cannot access resources unless @@ -99,7 +102,10 @@ authentication are supported by Admin Mode. Admin Mode status is stored in the c ### Turn off Admin Mode for your session -To turn off Admin Mode for your current session, on the top bar, select **Main menu > Leave Admin mode**. +To turn off Admin Mode for your current session: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Leave Admin Mode**. ### Limitations of Admin Mode @@ -173,8 +179,10 @@ For example, if you include the following information in the noted text box: To access this text box: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, and expand the **Sign-in restrictions** section. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand the **Sign-in restrictions** section. ``` Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 3bf52bfe001..0dcca5e7518 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -22,8 +22,10 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Sign-up restrictions**. 1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. ## Require administrator approval for new sign ups @@ -38,8 +40,10 @@ enabled by default for new GitLab instances. It is only applicable if sign ups a To require administrator approval for new sign ups: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Sign-up restrictions**. 1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273258), if an administrator disables this setting, the users in pending approval state are @@ -50,6 +54,7 @@ This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for n signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the [OmniAuth configuration](../../../integration/omniauth.md#configure-common-settings) or [LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings). +A [user cap](#user-cap) can also be used to enforce approvals for new users. ## Confirm user email @@ -61,8 +66,10 @@ their email address before they are allowed to sign in. For example, to enforce confirmation of the email address used for new sign ups: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Sign-up restrictions**. 1. Under **Email confirmation settings**, select **Hard**. The following settings are available: @@ -83,10 +90,22 @@ their account. If an administrator [increases](#set-the-user-cap-number) or [removes](#remove-the-user-cap) the user cap, the users in pending approval state are automatically approved in a background job. +NOTE: +The amount of billable users [is updated once a day](../../../subscriptions/self_managed/index.md#billable-users). +This means the user cap might apply only retrospectively after the cap has already been exceeded. +To ensure the cap is enabled immediately, set it to a low value below the current number of +billable users, for example: `1`. + +On instances that use LDAP or OmniAuth, enabling and disabling +[administrator approval for new sign ups](#require-administrator-approval-for-new-sign-ups) +involves changing the Rails configuration, and may require downtime. +User cap can be used instead. As noted above, set the cap to value that ensures it is enforced immediately. + ### Set the user cap number -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. 1. Select **Save changes**. @@ -95,8 +114,9 @@ New user sign ups are subject to the user cap restriction. ## Remove the user cap -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. 1. Select **Save changes**. @@ -123,8 +143,9 @@ You can add additional complexity requirements. Changes to password complexity r Existing passwords are unaffected. To change password complexity requirements: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Under **Minimum password length (number of characters)**, select additional password complexity requirements. You can require numbers, uppercase letters, lowercase letters, and symbols. @@ -152,8 +173,10 @@ reduce the risk of malicious users creating spam accounts with disposable email To create an email domain allowlist or denylist: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Sign-up restrictions**. 1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list manually or upload a `.txt` file that contains list entries. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 85927bad8ad..8563f778292 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -17,8 +17,9 @@ for example `https://gitlab.example.com/-/users/terms`. To enforce acceptance of a Terms of Service and Privacy Policy: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. 1. Input the text of the **Terms of Service and Privacy Policy**. You can use [Markdown](../../markdown.md) diff --git a/doc/user/admin_area/settings/terraform_limits.md b/doc/user/admin_area/settings/terraform_limits.md index 05b1f2d8838..0e620bb84ce 100644 --- a/doc/user/admin_area/settings/terraform_limits.md +++ b/doc/user/admin_area/settings/terraform_limits.md @@ -15,8 +15,9 @@ state file version, and is checked whenever a new version is created. To add a storage limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Terraform limits**. 1. Adjust the size limit. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 6037b24a294..39e2275f411 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -18,8 +18,10 @@ questions when creating a group. To toggle the display of customer experience improvement content and third-party offers: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings**, and expand **Customer experience improvement & third-party offers**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Customer experience improvement and third-party offers**. 1. Select **Do not display content for customer experience improvement and offers from third parties**. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index ba226e0f05b..ed0c8d21931 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -14,7 +14,7 @@ All usage statistics are [opt-out](#enable-or-disable-usage-statistics). ## Service Ping Service Ping is a process that collects and sends a weekly payload to GitLab Inc. -For more information, see the [Service Ping guide](../../../development/service_ping/index.md). When Service Ping is enabled, GitLab gathers data from other instances and enables certain [instance-level analytics features](../analytics/index.md) +For more information, see the [Service Ping guide](../../../development/internal_analytics/service_ping/index.md). When Service Ping is enabled, GitLab gathers data from other instances and enables certain [instance-level analytics features](../analytics/index.md) that are dependent on Service Ping. ### Why enable Service Ping? @@ -64,8 +64,9 @@ Registration is not yet required for participation, but may be added in a future ### Enable registration features 1. Sign in as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Metrics and profiling**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. If not enabled, select the **Enable Service Ping** checkbox. 1. Select the **Enable Registration Features** checkbox. @@ -112,7 +113,7 @@ sequenceDiagram ## Configure your network To send usage statistics to GitLab Inc., you must allow network traffic from your -GitLab instance to the IP address `104.196.17.203:443`. +GitLab instance to the host `version.gitlab.com` on port `443`. If your GitLab instance is behind a proxy, set the appropriate [proxy configuration variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html). @@ -121,8 +122,9 @@ If your GitLab instance is behind a proxy, set the appropriate To enable or disable Service Ping and version check: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Metrics and profiling**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Select or clear the **Enable version check** and **Enable Service Ping** checkboxes. 1. Select **Save changes**. @@ -136,7 +138,7 @@ The payload is available in the [Service Usage data](#manually-upload-service-pi NOTE: The method to disable Service Ping in the GitLab configuration file does not work in -GitLab versions 9.3 to 13.12.3. For more information about how to disable it, see [troubleshooting](../../../development/service_ping/troubleshooting.md#cannot-disable-service-ping-with-the-configuration-file). +GitLab versions 9.3 to 13.12.3. For more information about how to disable it, see [troubleshooting](../../../development/internal_analytics/service_ping/troubleshooting.md#cannot-disable-service-ping-with-the-configuration-file). To disable Service Ping and prevent it from being configured in the future through the Admin Area: @@ -178,12 +180,13 @@ the Admin Area: You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: 1. Sign in as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Metrics and profiling**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. Select **Preview payload**. -For an example payload, see [Example Service Ping payload](../../../development/service_ping/index.md#example-service-ping-payload). +For an example payload, see [Example Service Ping payload](../../../development/internal_analytics/service_ping/index.md#example-service-ping-payload). ## Manually upload Service Ping payload @@ -191,13 +194,14 @@ For an example payload, see [Example Service Ping payload](../../../development/ > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83265) in GitLab 14.10. You can upload the Service Ping payload to GitLab even if your instance doesn't have internet access, -or if the Service Ping [cron job](../../../development/service_ping/index.md#how-service-ping-works) is not enabled. +or if the Service Ping [cron job](../../../development/internal_analytics/service_ping/index.md#how-service-ping-works) is not enabled. To upload the payload manually: 1. Sign in as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Service** usage data. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Service** usage data. 1. Select **Download payload**. 1. Save the JSON file. 1. Visit [Service usage data center](https://version.gitlab.com/usage_data/new). @@ -211,7 +215,8 @@ If there are problems with the manual upload: 1. Open a confidential issue in the [security fork of version app project](https://gitlab.com/gitlab-org/security/version.gitlab.com). 1. Attach the JSON payload if possible. -1. Tag `@gitlab-org/analytics-section/product-intelligence` who will triage the issue. +1. Tag `@gitlab-org/analytics-section/analytics-instrumentation` who will triage the issue. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index 9b8718fc336..d145c351f3e 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -31,8 +31,10 @@ counted as web traffic. To enable the unauthenticated request rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **User and IP rate limits**. 1. Select **Enable unauthenticated API request rate limit**. - Optional. Update the **Maximum unauthenticated API requests per rate limit period per IP** value. @@ -44,8 +46,10 @@ To enable the unauthenticated request rate limit: To enable the unauthenticated request rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **User and IP rate limits**. 1. Select **Enable unauthenticated web request rate limit**. - Optional. Update the **Maximum unauthenticated web requests per rate limit period per IP** value. @@ -57,8 +61,10 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **User and IP rate limits**. 1. Select **Enable authenticated API request rate limit**. - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. @@ -70,8 +76,10 @@ To enable the authenticated API request rate limit: To enable the unauthenticated request rate limit: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **User and IP rate limits**. 1. Select **Enable authenticated web request rate limit**. - Optional. Update the **Maximum authenticated web requests per rate limit period per user** value. @@ -88,8 +96,10 @@ plain-text body, which by default is `Retry later`. To use a custom response: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Network**. +1. Expand **User and IP rate limits**. 1. In the **Plain-text response to send to clients that hit a rate limit** text box, add the plain-text response message. @@ -131,7 +141,7 @@ GitLab. For example: - Set `Gitlab-Bypass-Rate-Limiting` to a value other than `1` on all requests that should be affected by rate limiting. 1. Set the environment variable `GITLAB_THROTTLE_BYPASS_HEADER`. - - For [Omnibus](https://docs.gitlab.com/omnibus/settings/environment-variables.html), + - For [Linux package installations](https://docs.gitlab.com/omnibus/settings/environment-variables.html), set `'GITLAB_THROTTLE_BYPASS_HEADER' => 'Gitlab-Bypass-Rate-Limiting'` in `gitlab_rails['env']`. - For source installations, set `export GITLAB_THROTTLE_BYPASS_HEADER=Gitlab-Bypass-Rate-Limiting` in `/etc/default/gitlab`. @@ -163,7 +173,7 @@ the `GITLAB_THROTTLE_USER_ALLOWLIST` environment variable. If you want users 1, 53 and 217 to bypass the authenticated request rate limiter, the allowlist configuration would be `1,53,217`. -- For [Omnibus](https://docs.gitlab.com/omnibus/settings/environment-variables.html), +- For [Linux package installations](https://docs.gitlab.com/omnibus/settings/environment-variables.html), set `'GITLAB_THROTTLE_USER_ALLOWLIST' => '1,53,217'` in `gitlab_rails['env']`. - For source installations, set `export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217` in `/etc/default/gitlab`. diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index edcf1a80aca..dd53efaf518 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -13,19 +13,21 @@ specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. ## Define which roles can create projects Instance-level protections for project creation define which roles can -[add projects to a group](../../group/manage.md#specify-who-can-add-projects-to-a-group) +[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group) on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. For **Default project creation protection**, select the desired roles: - No one. @@ -40,8 +42,9 @@ on the instance. To alter which roles have permission to create projects: By default both administrators and anyone with the **Owner** role can delete a project. To restrict project deletion to only administrators: 1. Sign in to GitLab as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: - (GitLab 15.1 and later) **Allowed to delete projects**, and select **Administrators**. @@ -55,8 +58,7 @@ By default both administrators and anyone with the **Owner** role can delete a p > - [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. > - [Removed option to delete immediately](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default. -> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) on May 08, 2023. -> - Enabled delayed deletion by default and removed the option to delete immediately [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. +> - 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. Instance-level protection against accidental deletion of groups and projects. @@ -72,17 +74,15 @@ then it gets automatically changed to `1` while also disabling deletion protecti ### Delayed project deletion -> User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. - -Administrators can enable [delayed project deletion](../../project/settings/index.md#delayed-project-deletion) by default for -newly-created groups. Group owners can choose to disable this. When disabled, existing groups retain their existing setting. When enabled -deleted groups remain restorable within a retention period. +> - User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. +> - 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. To configure delayed project deletion: 1. Sign in to GitLab as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: - (In GitLab 15.11 and later with `always_perform_delayed_deletion` feature flag enabled, or GitLab 16.0 and later) **Deletion protection** and set the retention period to a value between `1` and `90`. @@ -97,7 +97,8 @@ In GitLab 15.1, and later this setting is enforced on groups when disabled and i ### Delayed group deletion -> User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. +> - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. +> - [Changed to default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) on the Premium and Ultimate tier in GitLab 16.0. Groups remain restorable if the retention period is `1` or more days. @@ -120,8 +121,9 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../public_access.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default project visibility: - **Private** - Project access must be granted explicitly to each user. If this @@ -135,8 +137,9 @@ To set the default [visibility levels for new projects](../../public_access.md): To set the default visibility levels for new [snippets](../../snippets.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default snippet visibility. 1. Select **Save changes**. @@ -149,8 +152,9 @@ For more details on snippet visibility, read To set the default visibility levels for new groups: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default group visibility: - **Private** - The group and its projects can only be viewed by members. @@ -170,8 +174,9 @@ the item you're changing. To restrict visibility levels for groups, projects, snippets, and selected pages: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. - If you restrict the **Public** level: @@ -195,8 +200,9 @@ Before you can import projects from other systems, you must enable the [import source](../../gitlab_com/index.md#default-import-sources) for that system. 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select each of **Import sources** to allow. 1. Select **Save changes**. @@ -207,8 +213,9 @@ To enable the export of [projects and their data](../../project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to **Project export**. 1. Select the **Enabled** checkbox. @@ -223,8 +230,9 @@ You can enable migration of groups by direct transfer using the UI. To enable migration of groups by direct transfer: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to **Allow migrating GitLab groups and projects by direct transfer**. 1. Select the **Enabled** checkbox. @@ -244,8 +252,9 @@ The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired Git access protocols: - Both SSH and HTTP(S) @@ -330,8 +339,9 @@ include the `10.0.0.0/24` range. To add a IP address range to the group-level allowlist: 1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In **Globally-allowed IP ranges**, provide a list of IP address ranges. This list: - Has no limit on the number of IP address ranges. diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index b47ae561689..6f2798f437c 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -34,6 +34,7 @@ How do we measure the activity of users? GitLab considers a user active if: To view user cohorts: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select the **Cohorts** tab. diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index 7c9480d308f..d5f7201556e 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -11,22 +11,25 @@ GitLab is creating AI-assisted features across our DevSecOps platform. These fea ## Enable AI/ML features -> Introduced in GitLab 16.0 and is [actively being rolled out](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222). +> Introduced in GitLab 16.0 and [actively being rolled out](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222). Prerequisites: - You must have the Owner role for the group. -To enable AI/ML features: +To enable AI/ML features for a top-level group: -- Enable the [Experiment features setting](group/manage.md#group-experiment-features-setting). -- The [third-party AI features setting](group/manage.md#group-third-party-ai-features-setting) is enabled by default. To disable AI features powered by third-party APIs, disable this setting. +- Enable [Experiment features](group/manage.md#enable-experiment-features). +- Enable [third-party AI features](group/manage.md#enable-third-party-ai-features) (enabled by default). + To disable AI features powered by third-party APIs, clear this setting. -These settings give you control over which features are enabled. These settings work together so you can have a mix of both experimental and third-party AI features. +These settings work together so you can have a mix of both experimental and third-party AI features. ## Generally Available AI features -When a feature is [Generally Available](../policy/alpha-beta-support.md#generally-available-ga), it does not require the [group-level Experiment features setting](group/manage.md#group-experiment-features-setting) to be enabled. Some of these features might require the [group-level third-party AI features setting](group/manage.md#group-third-party-ai-features-setting). +When a feature is [Generally Available](../policy/experiment-beta-support.md#generally-available-ga), +it does not require [Experiment features to be enabled](group/manage.md#enable-experiment-features). +Some of these features might require [third-party AI features to be enabled](group/manage.md#enable-third-party-ai-features). The following feature is Generally Available: @@ -34,7 +37,8 @@ The following feature is Generally Available: ## Beta AI features -[Beta features](../policy/alpha-beta-support.md#beta) do not require the [group-level Experiment features setting](group/manage.md#group-experiment-features-setting) to be enabled. +[Beta features](../policy/experiment-beta-support.md#beta) do not require +[Experiment features to be enabled](group/manage.md#enable-experiment-features). The following feature is in Beta: @@ -42,17 +46,20 @@ The following feature is in Beta: ## Experiment AI features -[Experiment features](../policy/alpha-beta-support.md#experiment) will soon require the [group-level Experiment features setting](group/manage.md#group-experiment-features-setting) to be enabled. +[Experiment features](../policy/experiment-beta-support.md#experiment) will soon require +[Experiment features to be enabled](group/manage.md#enable-experiment-features). ## Third-party AI features -Third-party AI features require the [group-level third-party AI features setting](group/manage.md#group-third-party-ai-features-setting) to be enabled. Experiment third-party AI features also require the [Experiment features setting](group/manage.md#group-experiment-features-setting) to be enabled. +Third-party AI features require [third-party AI services to be enabled](group/manage.md#enable-third-party-ai-features). + +For Experiment third-party AI features, [Experiment features must be enabled](group/manage.md#enable-experiment-features) as well. ### Explain Selected Code in the Web UI **(ULTIMATE SAAS)** -> Introduced in GitLab 15.11 as an [Experiment](../policy/alpha-beta-support.md#experiment) on GitLab.com. +> Introduced in GitLab 15.11 as an [Experiment](../policy/experiment-beta-support.md#experiment) on GitLab.com. -This feature is an [Experiment](../policy/alpha-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. +This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. GitLab can help you get up to speed faster if you: @@ -69,8 +76,8 @@ Prerequisites: To explain your code: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**, then select your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Code > Merge requests**, then select your merge request. 1. On the secondary menu, select **Changes**. 1. Go to the file, and select the lines that you want to have explained. 1. On the left side, select the question mark (**{question}**). You might have to scroll to the first line of your selection to view it. This sends the selected code, together with a prompt, to provide an explanation to the large language model. @@ -83,9 +90,9 @@ We cannot guarantee that the large language model produces results that are corr ### Explain this Vulnerability in the Web UI **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [Experiment](../policy/alpha-beta-support.md#experiment) on GitLab.com. +> [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. -This feature is an [Experiment](../policy/alpha-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 that is powered by Google AI. GitLab can help you with your vulnerability by using a large language model to: @@ -101,8 +108,8 @@ Prerequisites: To explain your vulnerability: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +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**. @@ -115,9 +122,9 @@ We cannot guarantee that the large language model produces results that are corr ### GitLab Chat **(ULTIMATE SAAS)** -> Introduced in GitLab 16.0 as an [Experiment](../policy/alpha-beta-support.md#experiment). +> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). -This feature is an [Experiment](../policy/alpha-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#group-third-party-ai-features-setting) to be enabled. +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 Chat. @@ -129,11 +136,15 @@ To give feedback, select the **Give Feedback** link. ### Summarize merge request changes **(ULTIMATE SAAS)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10400) in GitLab 16.0 as an [Experiment](../policy/alpha-beta-support.md#experiment). +> [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. -This feature is an [Experiment](../policy/alpha-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#group-third-party-ai-features-setting) to be enabled. +You can generate a merge request summary in a merge request comment. -You can generate a merge request summary by using the `/summarize_diff` quick action in a merge request comment. 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. +- 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). @@ -142,16 +153,19 @@ 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/alpha-beta-support.md#experiment). +> [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 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. -This feature is an [Experiment](../policy/alpha-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#group-third-party-ai-features-setting) 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. -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 choose to have summary generated for you. To generate the summary: +To generate the summary: -1. Select the AI Actions dropdown list. +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 generated and entered in to the comment box where you can edit and refine prior to submitting with your review. +The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. Provide feedback on this experimental feature in [issue 408991](https://gitlab.com/gitlab-org/gitlab/-/issues/408991). @@ -162,16 +176,19 @@ Provide feedback on this experimental feature in [issue 408991](https://gitlab.c ### 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/alpha-beta-support.md#experiment). +> [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/alpha-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#group-third-party-ai-features-setting) to be enabled. +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 in a merge request you can choose to have GitLab suggest tests for the file you are reviewing. This can help to determine if appropriate test coverage has been provided or help with writing tests to provide more coverage for your project. To generate a test suggestion: +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. -1. Select the menu icon on the header of a file. -1. Select **Generate test with AI**. +To generate a test suggestion: -A sidebar opens where the test suggestion is generated. From there you can choose to copy that suggestion in to your editor as the start of your tests. +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). @@ -180,17 +197,37 @@ Feedback on this experimental feature can be provided in [issue 408995](https:// - Contents of the file - The file name +### Summarize issue discussions **(ULTIMATE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10344) 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 summary of discussions on an issue: + +1. In an issue, scroll to the **Activity** section. +1. Select **View summary**. + +The comments in the issue are summarized in as many as 10 list items. +The summary is displayed only for you. + +Provide feedback on this experimental feature in [issue 407779](https://gitlab.com/gitlab-org/gitlab/-/issues/407779). + +**Data usage**: When you use this feature, the text of public comments on the issue are sent to the large +language model referenced above. + ## Data Usage GitLab AI features leverage generative AI to help increase velocity and aim to help make you more productive. Each feature operates independently of other features and is not required for other features to function. ### 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/alpha-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. Please 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 -These features are in a variety of [feature support levels](../policy/alpha-beta-support.md#beta). Due to the nature of these features, there may be high demand for usage which may cause degraded performance or unexpected downtime of the feature. We have built these features to gracefully degrade and have controls in place to allow us to mitigate abuse or misuse. GitLab may disable **beta and experimental** features for any or all customers at any time at our discretion. +These features are in a variety of [feature support levels](../policy/experiment-beta-support.md#beta). Due to the nature of these features, there may be high demand for usage which may cause degraded performance or unexpected downtime of the feature. We have built these features to gracefully degrade and have controls in place to allow us to mitigate abuse or misuse. GitLab may disable **beta and experimental** features for any or all customers at any time at our discretion. ## Third party services @@ -198,7 +235,7 @@ These features are in a variety of [feature support levels](../policy/alpha-beta 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. -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#group-third-party-ai-features-setting). +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). ### Model accuracy and quality diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md new file mode 100644 index 00000000000..e29e02c867f --- /dev/null +++ b/doc/user/analytics/analytics_dashboards.md @@ -0,0 +1,177 @@ +--- +stage: Analyze +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)** + +> 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. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +## Dashboards + +Each project can have an unlimited number of dashboards, only limited by the instances [repository size limits](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). +These dashboards are defined using the GitLab YAML schema, and stored in the `.gitlab/analytics/dashboards/` directory of a project repository. +The dashboard file name and containing directory should be the same, for example `my_dashboard/my_dashboard.yaml`. For more information see [defining a dashboard](#define-a-dashboard). +Each dashboard can reference one or more [visualizations](#define-a-chart-visualization), which are shared across dashboards. + +Project maintainers can enforce approval rules on dashboard changes using features such as [code owners](../project/codeowners/index.md) and [approval rules](../project/merge_requests/approvals/rules.md). +Your dashboard files are versioned in source control with the rest of a project's code. + +### Data sources + +A data source is a connection to a database or collection of data which can be used by your dashboard +filters and visualizations to query and retrieve results. + +The following data sources are configured for analytics dashboards: + +- [Product analytics](../product_analytics/index.md) + +### View project dashboards + +To view a list of dashboards for a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Dashboards**. +1. From the list of available dashboards, select the dashboard you want to view. + +### Define a dashboard + +To define a dashboard: + +1. In `.gitlab/analytics/dashboards/`, create a directory named like the dashboard. + + Each dashboard should have its own directory. +1. In the new directory, create a `.yaml` file with the same name as the directory, for example `.gitlab/analytics/dashboards/my_dashboard/my_dashboard.yaml`. + + This file contains the dashboard definition. It must conform to the JSON schema defined in `ee/app/validators/json_schemas/analytics_dashboard.json`. +1. Optional. To create new visualizations to add to your dashboard see [defining a chart visualization](#define-a-chart-visualization). + +For [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/analytics/product_analytics/dashboards/audience.yaml), if you want to create three dashboards (Conversion funnels, Demographic breakdown, and North star metrics) +and one visualization (line chart) that applies to all dashboards, the file structure would be: + +```plaintext +.gitlab/analytics/dashboards +├── conversion_funnels +│ └── conversion_funnels.yaml +├── demographic_breakdown +│ └── demographic_breakdown.yaml +├── north_star_metrics +| └── north_star_metrics.yaml +├── visualizations +│ └── example_line_chart.yaml +``` + +### Define a chart visualization + +You can define different charts, and add visualization options to some of them: + +- Line chart, with the options listed in the [ECharts documentation](https://echarts.apache.org/en/option.html). +- Column chart, with the options listed in the [ECharts documentation](https://echarts.apache.org/en/option.html). +- Data table, with the only option to render `links` (array of objects, each with `text` and `href` properties to specify the dimensions to be used in links). See [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/analytics_visualization.json?ref_type=heads#L112)). +- Single stat, with the only option to set `decimalPlaces` (number, default value is 0). + +To define a chart for your dashboards: + +1. In the `.gitlab/analytics/dashboards/visualizations/` directory, create a `.yaml` file. + The filename should be descriptive of the visualization it defines. +1. In the `.yaml` file, define the visualization configuration, according to the schema in + `ee/app/validators/json_schemas/analytics_visualization.json`. + +For [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/analytics/product_analytics/visualizations/events_over_time.yaml), to create a line chart that illustrates event count over time, in the `visualizations` folder +create a `line_chart.yaml` file with the following required fields: + +- version +- type +- data +- options + +### Change the location of project dashboards + +Dashboards are usually defined in the project where analytics data is being retrieved. +However, you can also have a separate project for dashboards. +This is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects. + +NOTE: +You can share dashboards only between projects that are located in the same group. + +To change the location of project dashboards: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project, + or select **Create new...** (**{plus}**) and **New project/repository** + to create the project to store your dashboard files. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and find the project you want to use the dashboards for. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In the **Analytics Dashboards** section, select the project that contains the dashboard files. +1. Select **Save changes**. + +### Change the location of group dashboards + +NOTE: +This feature will be connected to group-level dashboards in [issue 411572](https://gitlab.com/gitlab-org/gitlab/-/issues/411572). + +If you want to use dashboards for a group, you must store the dashboard files in a project that belongs to that group. +You can change the source project of a group's dashboards at any time. + +To change the location of a group's dashboards: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In the **Analytics Dashboards** section, select the project that contains the dashboard files. +1. Select **Save changes**. + +## Dashboards designer + +> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. 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, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +NOTE: +This feature does not work in conjunction with the `product_analytics_snowplow_support` feature flag. + +You can use the dashboards designer to: + +- Create custom dashboards +- Rename custom dashboards +- Add visualizations to new and existing custom dashboards +- Resize or move panels within custom dashboards + +You cannot edit the built-in dashboards labeled as `By GitLab`. +To edit these dashboards you should create a new custom dashboard which uses the same visualizations. + +### Create a custom dashboard + +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 **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. +1. Optional. Drag or resize the selected panel how you prefer. +1. Select **Save**. + +### Edit a custom dashboard + +You can edit your custom dashboard's title and add or resize visualizations within the dashboard designer. + +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. 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. +1. Optional. From the **Add visualizations** list on the right, select other visualizations to add to the dashboard. +1. Optional. In the dashboard, select a panel and drag or resize it how you prefer. +1. Select **Save**. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index bde7fdc6c2d..daee21d2567 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -32,8 +32,8 @@ View pipeline duration history: To view CI/CD analytics: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > 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)** @@ -50,8 +50,8 @@ The deployment frequency chart is available for groups and projects. To view the deployment frequency chart: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > 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**. 1. Select the **Deployment frequency** tab. ![Deployment frequency](img/deployment_frequency_charts_v13_12.png) @@ -72,8 +72,8 @@ merge requests to be deployed to a production environment. This chart is availab To view the lead time for changes chart: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > 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**. 1. Select the **Lead time** tab. ![Lead time](img/lead_time_chart_v13_11.png) @@ -88,8 +88,8 @@ Time to restore service is one of the four DORA metrics that DevOps teams use fo To view the time to restore service chart: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > 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**. 1. Select the **Time to restore service** tab. ![Lead time](img/time_to_restore_service_charts_v15_1.png) @@ -104,6 +104,6 @@ Change failure rate is one of the four DORA metrics that DevOps teams use for me To view the change failure rate chart: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > 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**. 1. Select the **Change failure rate** tab. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 2e76252f7d3..646a85fc7a2 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -34,8 +34,8 @@ Prerequisite: To view code review analytics: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Code Review**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Code review analytics**. 1. Optional. Filter results: 1. Select the filter bar. 1. Select a parameter. You can filter merge requests by milestone and label. diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 44af9dc9dea..e78f55911e6 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -33,6 +33,8 @@ GitLab provides several analytics features at the group level. Some of these fea You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free. +- [Analytics dashboards](analytics_dashboards.md), enabled with the `combined_analytics_dashboards_editor` + [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) - [Application Security](../application_security/security_dashboard/index.md) - [CI/CD & DORA](ci_cd_analytics.md) - [Code Review](code_review_analytics.md) @@ -43,6 +45,16 @@ You can use GitLab to review analytics at the project level. Some of these featu - [Repository](repository_analytics.md) - [Value Stream](value_stream_analytics.md) +### Remove project analytics from the left sidebar + +By default, analytics for a project are displayed under the **Analyze** item in the left sidebar. To remove this item: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn off the **Analytics** toggle. +1. Select **Save changes**. + ## User-configurable analytics The following analytics features are available for users to create personalized views: diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 71ce13a725e..aaf33f48df2 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -15,8 +15,8 @@ prior. To access the chart: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Issue**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Issue analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 69ba5a67197..eeaa8271749 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -29,8 +29,8 @@ Prerequisite: To view merge request analytics: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Merge request**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Merge request analytics**. ## View the number of merge requests in a date range @@ -39,8 +39,8 @@ To view merge request analytics: To view the number of merge requests merged during a specific date range: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Merge request**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Merge request analytics**. 1. Optional. Filter results: 1. Select the filter bar. 1. Select a parameter. @@ -73,6 +73,6 @@ created and when it's merged. Closed and not yet merged merge requests are not i To view **Mean time to merge**: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Merge request**. The **Mean time to merge** number +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Merge request analytics**. The **Mean time to merge** number is displayed on the dashboard. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index 08bb579fd0a..f53b516dd0d 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -26,8 +26,8 @@ Prerequisite: - You must have at least the Reporter role for the group. -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Productivity**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Productivity analytics**. 1. Optional. Filter results: 1. Select a project from the dropdown list. 1. To filter results by author, milestone, or label, @@ -44,8 +44,8 @@ Use the following charts in productivity analytics to view the velocity of your merge requests to merge after they were created. - **Trendline**: number of merge requests that were merged in a specific time period. -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Productivity**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Productivity analytics**. To filter time metrics: @@ -56,8 +56,8 @@ To filter time metrics: To view commit statistics for your group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Productivity**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Productivity analytics**. 1. Under the **Trendline** scatterplot, view the commit statistics: - The left histogram shows the number of hours between commits, comments, and merges. - The right histogram shows the number of commits and changes per merge request. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index b434221b887..e686d76eda2 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -30,8 +30,8 @@ Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are no To review repository analytics for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Repository analytics**. ## How repository analytics chart data is updated diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index 384f4ce3455..9b332d78060 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -4,10 +4,10 @@ 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 (Beta) **(ULTIMATE)** +# Value Streams Dashboard **(ULTIMATE)** -> - Introduced in GitLab 15.8 as a Closed [Beta](../../policy/alpha-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/alpha-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default. +> - 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). @@ -21,17 +21,18 @@ For more information, see the [Value Stream Management category direction page]( Our initial use case is focused on providing the ability to compare software delivery metrics. This comparison can help decision-makers understand whether projects and groups are improving. -The beta version of the Value Streams Dashboard includes the following metrics: +The Value Streams Dashboard includes the following metrics: - [DORA metrics](dora_metrics.md) - [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: - Aggregate data records from different APIs. - Track software performance (DORA) and flow of value (VSA) across the organization. -## DevOps metrics comparison +## DevOps metrics comparison panel The DevOps metrics comparison displays DORA4 and flow metrics for a group or project in the month-to-date, last month, the month before, and the past 180 days. @@ -54,10 +55,8 @@ Prerequisite: To view the value streams dashboard: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +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 **Key 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`). @@ -88,15 +87,15 @@ Prerequisite: - You must have at least the Maintainer role for the group. -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Scroll to **Analytics Dashboards** and select **Expand**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Analytics**. 1. Select the project where you would like to store your YAML configuration file. 1. Select **Save changes**. After you have set up the project, set up the configuration file: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. In the default branch, create the configuration file: `.gitlab/analytics/dashboards/value_streams/value_streams.yaml`. 1. In the `value_streams.yaml` configuration file, fill in the configuration options: @@ -110,6 +109,7 @@ description: 'Custom description' # panels - List of panels that contain panel settings. # title - Change the title of the panel. [optional] # data.namespace - The Group or Project path to use for the chart panel. +# data.exclude_metrics - Hide rows by metric ID from the chart panel. panels: - title: 'My Custom Project' data: @@ -119,6 +119,9 @@ panels: - title: 'My Custom Group' data: namespace: group/my-custom-group + exclude_metrics: + - deployment_frequency + - change_failure_rate - data: namespace: group/another-group ``` @@ -133,15 +136,17 @@ panels: ## Dashboard metrics and drill-down reports -| Metric | Description | Drill-down report | Documentation page | -| ------ | ----------- | --------------- | ------------------ | -| Deployment frequency | Average number of deployments to production per day. This metric measures how often value is delivered to end users. | [Deployment frequency tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=deployment-frequency) | [Deployment frequency](dora_metrics.md#deployment-frequency) | -| Lead time for changes | The time to successfully deliver a commit into production. This metric reflects the efficiency of CI/CD pipelines. | [Lead time tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=lead-time) | [Lead time for changes](dora_metrics.md#lead-time-for-changes) | -| Time to restore service | The time it takes an organization to recover from a failure in production. | [Time to restore service tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=time-to-restore-service) | [Time to restore service](dora_metrics.md#time-to-restore-service) | -| Change failure rate | Percentage of deployments that cause an incident in production. | [Change failure rate tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=change-failure-rate) | [Change failure rate](dora_metrics.md#change-failure-rate) | -| Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | -| Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | -| New issues | Number of new issues created. | [Issue Analytics](https://gitlab.com/groups/gitlab-org/-/issues_analytics) | Issue analytics [for projects](issue_analytics.md) and [for groups](../../user/group/issues_analytics/index.md) | -| Number of deploys | Total number of deploys to production. | [Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Merge request analytics](merge_request_analytics.md) | -| 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) | -| 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) | +| Metric | Description | Drill-down report | Documentation page | ID | +| ------ | ----------- | --------------- | ------------------ | -- | +| Deployment frequency | Average number of deployments to production per day. This metric measures how often value is delivered to end users. | [Deployment frequency tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=deployment-frequency) | [Deployment frequency](dora_metrics.md#deployment-frequency) | `deployment_frequency` | +| Lead time for changes | The time to successfully deliver a commit into production. This metric reflects the efficiency of CI/CD pipelines. | [Lead time tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=lead-time) | [Lead time for changes](dora_metrics.md#lead-time-for-changes) | `lead_time_for_changes` | +| Time to restore service | The time it takes an organization to recover from a failure in production. | [Time to restore service tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=time-to-restore-service) | [Time to restore service](dora_metrics.md#time-to-restore-service) | `time_to_restore_service` | +| Change failure rate | Percentage of deployments that cause an incident in production. | [Change failure rate tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=change-failure-rate) | [Change failure rate](dora_metrics.md#change-failure-rate) | `change_failure_rate` | +| Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | `lead_time` | +| Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | `cycle_time` | +| New issues | Number of new issues created. | [Issue Analytics](https://gitlab.com/groups/gitlab-org/-/issues_analytics) | Issue analytics [for projects](issue_analytics.md) and [for groups](../../user/group/issues_analytics/index.md) | `issues` | +| Closed issues | Number of issues closed by month. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [Value Stream Analytics](../group/value_stream_analytics/index.md) | `issues_completed` | +| Number of deploys | Total number of deploys to production. | [Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Merge request analytics](merge_request_analytics.md) | `deploys` | +| 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` | diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index b613b0cc33e..28e72816a99 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -101,8 +101,8 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **API Fuzzing** row, select **Enable API Fuzzing**. 1. Complete the fields. For details see [Available CI/CD variables](#available-cicd-variables). 1. Select **Generate code snippet**. @@ -2606,14 +2606,6 @@ deploy-test-target: - environment_url.txt ``` -<!-- -### Target Container - -The API Fuzzing template supports launching a docker container containing an API target using docker-in-docker. - -TODO ---> - ### Use OpenAPI with an invalid schema There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Fuzzing is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. 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 95b53249653..c7ae47a7083 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -7,7 +7,7 @@ type: reference, howto # API Discovery **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9302) in GitLab 15.9. The API Discovery feature is in [Beta](../../../../policy/alpha-beta-support.md). +> [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). API Discovery analyzes your application and produces an OpenAPI document describing the web APIs it exposes. This schema document can then be used by [DAST API](../../dast_api/index.md) or [API Fuzzing](../../api_fuzzing/index.md) to perform security scans of the web API. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index d5a05477ddf..bbb7bf2f625 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -40,8 +40,8 @@ all security features are configured by default. To view a project's security configuration: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. Select **Configuration history** to see the `.gitlab-ci.yml` file's history. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 7a82f98425a..042ed0190c4 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -220,7 +220,7 @@ The `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` CI/CD variable controls whether the findings related to programming languages. The languages supported depend on the [scanner used](#change-scanners): -- [Trivy](https://aquasecurity.github.io/trivy/latest/docs/vulnerability/detection/language/). +- [Trivy](https://aquasecurity.github.io/trivy/v0.41/docs/scanner/vulnerability/language/) - [Grype](https://github.com/anchore/grype#features). By default, the report only includes packages managed by the Operating System (OS) package manager diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 09370a9a7f5..b0571c8a6ca 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -46,18 +46,20 @@ You can use the following fuzzing engines to test the specified languages. | Go | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | | Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | -| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java (Maven only)<sup>1</sup> | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | | Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | | JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz) | [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | | Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz) | [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | | AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/) | [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | +1. Support for Gradle is planned in [issue 409764](https://gitlab.com/gitlab-org/gitlab/-/issues/409764). + ## Confirm status of coverage-guided fuzz testing To confirm the status of coverage-guided fuzz testing: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section the status is: - **Not configured** - **Enabled** @@ -170,8 +172,8 @@ artifacts files you can download from the CI/CD pipeline. Also, a project member To view details of the corpus registry: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. ### Create a corpus in the corpus registry @@ -198,8 +200,8 @@ provided by the `COVFUZZ_CORPUS_NAME` variable. The corpus is updated on every p To upload an existing corpus file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. 1. Select **New corpus**. 1. Complete the fields. @@ -225,7 +227,7 @@ Prerequisites: ## Coverage-guided fuzz testing report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Experiment](../../../policy/alpha-beta-support.md#experiment). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Experiment](../../../policy/experiment-beta-support.md#experiment). For detailed information about the `gl-coverage-fuzzing-report.json` file's format, read the [schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index f65501712cc..499efd3f60d 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -89,8 +89,8 @@ In this method you manually edit the existing `.gitlab-ci.yml` file. Use this me To include the DAST template: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **CI/CD > Editor**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Build > Pipeline editor**. 1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file. To use the DAST stable template: @@ -156,8 +156,8 @@ snippet is created that you paste into the `.gitlab-ci.yml` file. To configure DAST using the UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Enable DAST** or **Configure DAST**. 1. Select the desired **Scanner profile**, or select **Create scanner profile** and save a @@ -548,8 +548,8 @@ The on-demand DAST scan runs and the project's dashboard shows the results. To run a saved on-demand scan: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. @@ -567,8 +567,8 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. To schedule a scan: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > On-demand scans**. 1. Select **New scan**. 1. Complete the **Scan name** and **Description** text boxes. 1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. @@ -715,8 +715,8 @@ Validating a site is required to run an active scan. To validate a site profile: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. 1. In the profile's row, select **Validate**. @@ -752,8 +752,8 @@ page. To retry a site profile's failed validation: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. 1. In the profile's row, select **Retry validation**. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index c510be55981..df9e1d72dba 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -578,8 +578,8 @@ always take the latest dependency scanning artifact available. To enable Dependency Scanning in a project, you can create a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Dependency Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable Dependency Scanning. @@ -864,7 +864,7 @@ Here's an example dependency scanning report: ### CycloneDX Software Bill of Materials -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/alpha-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/experiment-beta-support.md#beta). > - Generally available in GitLab 15.7. In addition to the [JSON report file](#reports-json-format), the [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 48b2b8c1f1a..8e2f54fed44 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -116,10 +116,13 @@ that you can download and analyze. ### Enable IaC Scanning via an automatic merge request +NOTE: +The **Configure with a merge request** button been temporarily disabled due to a known issue. For details, see [merge request 83757](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83757). + To enable IaC Scanning in a project, you can create a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable IaC Scanning. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index a3c512a813c..8bbe4db62a9 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -104,6 +104,7 @@ The following vulnerability scanners and their databases are regularly updated: | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. GitLab monitors this job through an internal alert that tells the engineering team when the database becomes more than 48 hours old. For more information, see the [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | | [Dependency Scanning](dependency_scanning/index.md) | Relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). It is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | +| [Secret Detection](secret_detection/index.md#detected-secrets) | GitLab maintains the [detection rules](secret_detection/index.md#detected-secrets) and [accepts community contributions](secret_detection/index.md#adding-new-patterns). The scanning engine is updated at least once per month if a relevant update is available. | | [Static Application Security Testing (SAST)](sast/index.md) | The source of scan rules depends on which [analyzer](sast/analyzers.md) is used for each [supported programming language](sast/index.md#supported-languages-and-frameworks). GitLab maintains a ruleset for the Semgrep-based analyzer and updates it regularly based on internal research and user feedback. For other analyzers, the ruleset is sourced from the upstream open-source scanner. Each analyzer is updated at least once per month if a relevant update is available. | In versions of GitLab that use the same major version of the analyzer, you do not have to update @@ -498,14 +499,12 @@ GitLab provides two methods of accomplishing this, each with advantages and disa are recommended when: - Scan execution enforcement is required for DAST which uses a DAST site or scan profile. - - Scan execution enforcement is required for SAST, Secret Detection, Dependency Scanning, or Container Scanning with project-specific + - Scan execution enforcement is required for SAST, SAST IaC, Secret Detection, Dependency Scanning, or Container Scanning with project-specific variable customizations. To accomplish this, users must create a separate security policy per project. - Scans are required to run on a regular, scheduled cadence. - Either solution can be used equally well when: - - Scan execution enforcement is required for SAST or Secret Detection when custom rulesets are not - used. - Scan execution enforcement is required for Container Scanning with no project-specific variable customizations. @@ -513,7 +512,7 @@ Additional details about the differences between the two solutions are outlined | | Compliance Framework Pipelines | Scan Execution Policies | | ------ | ------ | ------ | -| **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | +| **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, SAST IaC, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | | **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | | **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | | **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 0d821f8e47c..bd3da0b5913 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -58,8 +58,8 @@ to select, edit, and unlink a security policy project. As a project owner, take the following steps to create or edit an association between your current project and a project that you would like to designate as the security policy project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Policies**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Policies**. 1. Select **Edit Policy Project**, and search for and select the project you would like to link from the dropdown list. 1. Select **Save**. @@ -82,8 +82,8 @@ policies for all available environments. You can check a policy's information (for example, description or enforcement status), and create and edit deployed policies: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Policies**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Policies**. ![Policies List Page](img/policies_list_v15_1.png) @@ -93,8 +93,8 @@ status), and create and edit deployed policies: You can use the policy editor to create, edit, and delete policies: -1. On the top bar, select **Main menu > Projects** and find your group. -1. On the left sidebar, select **Security and Compliance > Policies**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Policies**. - To create a new policy, select **New policy** which is located in the **Policies** page's header. You can then select which type of policy to create. - To edit an existing policy, select **Edit policy** in the selected policy drawer. @@ -150,5 +150,6 @@ The workaround is to amend your group or instance push rules to allow branches f - When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is based on your server time for self managed instances. When testing new policies, it may appear pipelines are not running properly when in fact they are scheduled in your server's timezone. - When enforcing scan execution policies, 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. 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 61671efab63..e18d4d1787e 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -78,7 +78,8 @@ This rule enforces the defined actions whenever the pipeline runs for a selected | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| | `type` | `string` | `pipeline` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). Cannot be used with the `branch_type` field. | +| `branch_type` | `string` | `default`, `protected` or `all` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | ## `schedule` rule type @@ -87,7 +88,8 @@ This rule enforces the defined actions and schedules a scan on the provided date | Field | Type | Possible values | Description | |------------|------|-----------------|-------------| | `type` | `string` | `schedule` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). This field is required if the `agents` field is not set. | +| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). This field is required if the `agents` field is not set. Cannot be used with the `branch_type` field. | +| `branch_type` | `string` | `default`, `protected` or `all` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | | `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index ecbbf4703b0..d8cd984ad40 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -15,6 +15,9 @@ findings of one or more security scan jobs. Scan result policies are evaluated a NOTE: Scan result policies are applicable only to [protected](../../project/protected_branches.md) target branches. +NOTE: +When a protected branch is created or deleted, the policy approval rules synchronize, with a delay of 1 minute. + The following video gives you an overview of GitLab scan result policies: <div class="video-fallback"> diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index f52ff7f9a55..fecadaa737d 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -77,7 +77,7 @@ Work to remove language-specific analyzers and replace them with the Semgrep-bas You can choose to disable the other analyzers early and use Semgrep-based scanning for supported languages before the default behavior changes. If you do so: -- You enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. +- You enjoy significantly faster scanning, reduced compute quota usage, and more customizable scanning rules. - However, vulnerabilities previously reported by language-specific analyzers are reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: - whether you've excluded the Semgrep-based analyzer from running in the past. - which analyzer first discovered the vulnerabilities shown in the project's [Vulnerability Report](../vulnerability_report/index.md). diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index ddf8db4e489..385c5ffbae1 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -79,6 +79,37 @@ To create the ruleset configuration file: 1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. 1. Create a file named `sast-ruleset.toml` in the `.gitlab` directory. +## Specify a remote configuration file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393452) in 16.1. + +You can set a [CI/CD variable](../../../ci/variables/index.md) to use a ruleset configuration file that's stored outside of the current repository. +This can help you apply the same rules across multiple projects. + +The `SAST_RULESET_GIT_REFERENCE` variable uses a format similar to +[Git URLs](https://git-scm.com/docs/git-clone#_git_urls) for specifying a project URI, +optional authentication, and optional Git SHA. The variable uses the following format: + +```plaintext +[<AUTH_USER>[:<AUTH_PASSWORD>]@]<PROJECT_PATH>[@<GIT_SHA>] +``` + +NOTE: +If a project has a `.gitlab/sast-ruleset.toml` file committed, that local configuration takes precedence and the file from `SAST_RULESET_GIT_REFERENCE` isn't used. + +The following example [enables SAST](index.md#configure-sast-in-your-cicd-yaml) and uses a shared ruleset customization file. +In this example, the file is committed on the default branch of `example-ruleset-project` at the path `.gitlab/sast-ruleset.toml`. + +```yaml +include: + - template: Jobs/SAST.gitlab-ci.yml + +variables: + SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project" +``` + +See [specify a private remote configuration example](#specify-a-private-remote-configuration) for advanced usage. + ## Schema ### The top-level section @@ -352,23 +383,23 @@ The syntax used for the `value` follows the [njsscan config format](https://gith --- - nodejs-extensions: - .js - + template-extensions: - .new - .hbs - '' - + ignore-filenames: - skip.js - + ignore-paths: - __MACOSX - skip_dir - node_modules - + ignore-extensions: - .hbs - + ignore-rules: - regex_injection_dos - pug_jade_template @@ -560,3 +591,20 @@ rules: languages: - "go" ``` + +### Specify a private remote configuration + +The following example [enables SAST](index.md#configure-sast-in-your-cicd-yaml) and uses a shared ruleset customization file. The file is: + +- Downloaded from a private project that requires authentication, by using a [Group Access Token](../../group/settings/group_access_tokens.md). +- Checked out at a specific Git commit SHA instead of the default branch. + +See [group access tokens](../../group/settings/group_access_tokens.md#bot-users-for-groups) for how to find the username associated with a group token. + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +variables: + SAST_RULESET_GIT_REFERENCE: "group_2504721_bot_7c9311ffb83f2850e794d478ccee36f5:glpat-1234567@gitlab.com/example-group/example-ruleset-project@c8ea7e3ff126987fb4819cc35f2310755511c2ab" +``` diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 64c0f3440c5..2008375d2a2 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -301,8 +301,8 @@ successfully, and an error may occur. To enable and configure SAST with customizations: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. If the project does not have a `.gitlab-ci.yml` file, select **Enable SAST** in the Static Application Security Testing (SAST) row, otherwise select **Configure SAST**. 1. Enter the custom SAST values. @@ -328,8 +328,8 @@ successfully, and an error may occur. To enable and configure SAST with default settings: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance** > **Configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the SAST section, select **Configure with a merge request**. 1. Review and merge the merge request to enable SAST. @@ -617,6 +617,7 @@ flags are added to the scanner's CLI options. |------------------------------------------------------------------------------|--------------------|------------------------------------------------------------------------------| | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | `--max-memory` | Sets the maximum system memory to use when running a rule on a single file. Measured in MB. | | [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | `--neverignore` | Never ignore security issues, even if they have an “ignore” directive in a comment. Adding this option is likely to result in the analyzer detecting additional vulnerability findings which cannot be automatically resolved. | +| [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | `-effort` | Sets the analysis effort level. Valid values are `min`, `less`, `more` and `max`, defined in increasing order of scan's precision and ability to detect more vulnerabilities. Default value is set to `max` which may require more memory and time to complete the scan, depending on the project's size. In case you face memory or performance issues, you may reduce the analysis effort level to a lower value. For example: `-effort less`. | #### Custom CI/CD variables @@ -868,7 +869,7 @@ This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, ### 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/gitlab-sast/). +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` diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md index a898a63e33b..8f78d36976b 100644 --- a/doc/user/application_security/secret_detection/automatic_response.md +++ b/doc/user/application_security/secret_detection/automatic_response.md @@ -22,6 +22,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 | ✅ | ⚙ | **Component legend** diff --git a/doc/user/application_security/secret_detection/img/secret_detection_v13_2.png b/doc/user/application_security/secret_detection/img/secret_detection_v13_2.png Binary files differdeleted file mode 100644 index 4aa7dd83c8d..00000000000 --- a/doc/user/application_security/secret_detection/img/secret_detection_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 5a1dcc840ca..2e6de222ec3 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -107,7 +107,8 @@ Secret Detection can detect if a secret was added in one commit and removed in a In a merge request, Secret Detection scans every commit made on the source branch. To use this feature, you must use the [`latest` Secret Detection template](#templates), as it supports - [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). + [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). Secret Detection's + results are only available after the pipeline is completed. ## Templates @@ -116,7 +117,7 @@ provided with GitLab upgrades, allowing you to benefit from any improvements and Available templates: -- [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.gitlab-ci.yml): Stable version of the Secret Detection CI/CD template. +- [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.gitlab-ci.yml): Stable, default version of the Secret Detection CI/CD template. - [`Secret-Detection.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.latest.gitlab-ci.yml): Latest version of the Secret Detection template. WARNING: @@ -154,13 +155,13 @@ To enable Secret Detection, either: This method requires you to manually edit the existing `.gitlab-ci.yml` file. Use this method if your GitLab CI/CD configuration file is complex. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **CI/CD > Editor**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Build > Pipeline editor**. 1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file: ```yaml include: - - template: Jobs/Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml ``` 1. Select the **Validate** tab, then select **Validate pipeline**. @@ -187,8 +188,8 @@ error may occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manu To enable Secret Detection: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. In the **Secret Detection** row, select **Configure with a merge request**. 1. Optional. Complete the fields. 1. Select **Create merge request**. @@ -495,6 +496,36 @@ path = "/gitleaks.toml" ] ``` +## 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. + +The `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable uses an SCP-style syntax for specifying a URI, +optional authentication, and optional Git SHA. The variable uses the following format: + +```plaintext +<AUTH_USER>:<AUTH_PASSWORD>@<PROJECT_PATH>@<GIT_SHA> +``` + +NOTE: +Loading local project configuration takes precedence over `SECRET_DETECTION_RULESET_GIT_REFERENCE` values. + +The following example includes the Secret Detection template in a project to be scanned and specifies +the `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable for referencing a separate project configuration. + +```yaml +include: + - template: Jobs/Secret-Detection.gitlab-ci.yml + +variables: + SECRET_DETECTION_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project" +``` + +For more information on the syntax of remote configurations, see the +[specify a private remote configuration example](../sast/customize_rulesets.md#specify-a-private-remote-configuration) +on the SAST customize rulesets page. + ## Running Secret Detection in an offline environment **(PREMIUM SELF)** An offline environment has limited, restricted, or intermittent access to external resources through @@ -575,7 +606,9 @@ variable, or as a CI/CD variable. ## Warnings for potential leaks in text content -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368434) in GitLab 15.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368434) in GitLab 15.11. +> - Detection of personal access tokens with a custom prefix was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411146) +in GitLab 16.1. GitLab self-managed only. When you create an issue, propose a merge request, or write a comment, you might accidentally post a sensitive value. For example, you might paste in the details of an API request or an environment variable that contains an authentication token. @@ -588,6 +621,7 @@ The check is always on; you don't have to set it up. Your text is checked for the following secret types: - GitLab [personal access tokens](../../../security/token_overview.md#personal-access-tokens) + - If a [personal access token prefix](../../../user/admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) has been configured, a token using this prefix is checked. - GitLab [feed tokens](../../../security/token_overview.md#feed-token) This feature is separate from Secret Detection scanning, which checks your Git repository for leaked secrets. diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index e6cb4cef4b2..e28c06236aa 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -66,8 +66,8 @@ Project Security Dashboards show statistics for all vulnerabilities with a curre To view total number of vulnerabilities over time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security Dashboard**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security dashboard**. 1. Filter and search for what you need. - To filter the chart by severity, select the legend name. - To view a specific time frame, use the time range handles (**{scroll-handle}**). @@ -79,8 +79,8 @@ To view total number of vulnerabilities over time: To download an SVG image of the vulnerabilities chart: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security dashboard**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security dashboard**. 1. Select **Save chart as an image** (**{download}**). ## View vulnerabilities over time for a group @@ -90,8 +90,8 @@ branches of projects in a group and its subgroups. To view vulnerabilities over time for a group: -1. On the top bar, select **Main menu > Groups** and select a group. -1. Select **Security > Security Dashboard**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Security > Security dashboard**. 1. Hover over the chart to get more details about vulnerabilities. - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). - To view aggregated data beyond a 90-day time frame, use the @@ -104,8 +104,8 @@ Use the group Security Dashboard to view the security status of projects. To view project security status for a group: -1. On the top bar, select **Main menu > Groups** and select a group. -1. Select **Security > Security Dashboard**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Secure > Security dashboard**. Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and appears only once @@ -140,14 +140,20 @@ The Security Center includes: ### View the Security Center -To view the Security Center, on the top bar, select **Main menu > Security**. +To view the Security Center: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. +1. Select **Security > Security dashboard**. ### Add projects to the Security Center To add projects to the Security Center: -1. On the top bar, select **Main menu > Security**. -1. On the left sidebar, select **Settings**, or select **Add projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. +1. Expand **Security**. +1. Select **Settings**. 1. Use the **Search your projects** text box to search for and select projects. 1. Select **Add projects**. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 18485f83fe7..39d8e28e564 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Page **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in GitLab 13.0. - Each vulnerability in a project has a vulnerability page containing details of the vulnerability, including: @@ -35,8 +33,9 @@ A vulnerability's status can be: - **Dismissed**: A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. Dismissed vulnerabilities are ignored if detected in subsequent scans. -- **Resolved**: The vulnerability has been fixed or is no longer present. Resolved vulnerabilities - that are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. +- **Resolved**: The vulnerability has been fixed or is no longer present. If a resolved + vulnerability is reintroduced and detected again, its record is reinstated and its status set to + detected. ## Vulnerability dismissal reasons @@ -56,8 +55,8 @@ When dismissing a vulnerability, one of the following reasons must be chosen to To change a vulnerability's status from its Vulnerability Page: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Status** dropdown list select a status, then select **Change status**. @@ -86,8 +85,8 @@ that when Jira integration is enabled, the GitLab issue feature is not available To create a GitLab issue for a vulnerability: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create issue**. @@ -96,9 +95,6 @@ The issue is then opened so you can take further action. ### Create a Jira issue for a vulnerability -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4677) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/283850) in GitLab 13.12. - Prerequisites: - [Enable Jira integration](../../../integration/jira/index.md). The **Enable Jira issue creation @@ -108,8 +104,8 @@ Prerequisites: To create a Jira issue for a vulnerability: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create Jira issue**. 1. If you're not already logged in to Jira, sign in. @@ -141,8 +137,8 @@ Be aware of the following conditions between a vulnerability and a linked issue: To link a vulnerability to existing issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. In the **Linked issues** section, select the plus icon (**{plus}**). 1. For each issue to be linked, either: @@ -176,8 +172,8 @@ To resolve a vulnerability, you can either: To resolve the vulnerability with a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Resolve with merge request**. @@ -188,8 +184,8 @@ Process the merge request according to your standard workflow. To manually apply the patch that GitLab generated for a vulnerability: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Download patch to resolve**. 1. Ensure your local project has the same commit checked out that was used to generate the patch. @@ -210,8 +206,8 @@ Security training helps your developers learn how to fix vulnerabilities. Develo To enable security training for vulnerabilities in your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Security configuration**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. 1. On the tab bar, select **Vulnerability Management**. 1. To enable a security training provider, turn on the toggle. @@ -228,7 +224,7 @@ Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select the vulnerability for which you want to view security training. 1. Select **View training**. diff --git a/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png Binary files differdeleted file mode 100644 index bfde7cd6c80..00000000000 --- a/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 0826258de9e..78f8bbdb0c3 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -7,9 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** -The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. - -The scan results from a pipeline are only ingested after all the jobs in the pipeline complete. Partial results for a pipeline with jobs in progress can be seen in the pipeline security tab. +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 +pipeline are only ingested after all the jobs in the pipeline complete. The report is available for users with the [correct role](../../permissions.md) on projects, groups, and the Security Center. @@ -31,6 +31,11 @@ in that row: - False positive **{false-positive}**: The scanner determined this vulnerability to be a false positive. +To open an issue created for a vulnerability, hover over the **Activity** entry, then select the link. +The issue icon (**{issues}**) indicates the issue's status. If Jira issue support is enabled, the +issue link found in the **Activity** entry links out to the issue in Jira. Unlike GitLab issues, the +status of a Jira issue is not shown in the GitLab UI. + ![Example project-level Vulnerability Report](img/project_level_vulnerability_report_v14_5.png) ## Project-level Vulnerability Report @@ -47,8 +52,8 @@ At the project level, the Vulnerability Report also contains: To view the project-level vulnerability report: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. ## Vulnerability Report actions @@ -57,7 +62,6 @@ From the Vulnerability Report you can: - [Filter the list of vulnerabilities](#filter-the-list-of-vulnerabilities). - [View more details about a vulnerability](#view-details-of-a-vulnerability). - [View vulnerable source location](#view-vulnerable-source-location) (if available). -- [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). - [Change the status of vulnerabilities](#change-status-of-vulnerabilities). - [Export details of vulnerabilities](#export-vulnerability-details). - [Sort vulnerabilities by date](#sort-vulnerabilities-by-date-detected). @@ -72,7 +76,8 @@ The available filters are: <!-- vale gitlab.SubstitutionWarning = NO --> -- **Status**: Detected, Confirmed, Dismissed, Resolved. +- **Status**: Detected, Confirmed, Dismissed, Resolved. For details on what each status means, see + [vulnerability status values](../vulnerabilities/index.md#vulnerability-status-values). - **Severity**: Critical, High, Medium, Low, Info, Unknown. - **Tool**: For more details, see [Tool filter](#tool-filter). - **Project**: For more details, see [Project filter](#project-filter). @@ -150,15 +155,6 @@ in the default branch. To view the relevant file, select the filename in the vulnerability's details. -## View issues raised for a vulnerability - -The **Activity** column indicates the number of issues that have been created for the vulnerability. -Hover over an **Activity** entry and select a link go to that issue. The status of whether the issue is open or closed also displays in the hover menu. - -![Display attached issues](img/vulnerability_list_table_v13_9.png) - -If Jira issue support is enabled, the issue link found in the Activity entry links out to the issue in Jira. Unlike GitLab issues, the status of whether a Jira issue is Open or Closed does not display in the GitLab UI. - ## Change status of vulnerabilities > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. @@ -261,8 +257,8 @@ To undo this action, select a different status from the same menu. To add a new vulnerability finding from your project level Vulnerability Report page: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security and Compliance > Vulnerability Report**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Vulnerability report**. 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 0e5bb5e10f7..a53e0a8970b 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -11,8 +11,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w To view vulnerabilities in a pipeline: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **CI/CD > Pipelines**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Build > Pipelines**. 1. From the list, select the pipeline you want to check for vulnerabilities. 1. Select the **Security** tab. diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 6b642363dd6..f04fece7b76 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -244,9 +244,6 @@ pages, change the filename from `.adoc` to `.asciidoc`. ```plaintext include::basics.adoc[] - -// define -a allow-uri-read to allow content to be read from URI -include::https://example.org/installation.adoc[] ``` To guarantee good system performance and prevent malicious documents from causing @@ -254,6 +251,14 @@ problems, GitLab enforces a maximum limit on the number of include directives processed in any one document. You can include up to 32 documents, which is inclusive of transitive dependencies. +To use includes from separate pages or external URLs, enable the `allow-uri-read` +in [application settings](../administration/wikis/index.md#allow-uri-includes-for-asciidoc). + +```plaintext +// define application setting allow-uri-read to true to allow content to be read from URI +include::https://example.org/installation.adoc[] +``` + ### Blocks ```plaintext diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 7a3f09f50ca..a0b42101dd5 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. -> - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. +> - Support for Linux package installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. > - The ability to switch between certificate-based clusters and agents was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335089) in GitLab 14.9. The certificate-based cluster context is always called `gitlab-deploy`. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80508) from _CI/CD tunnel_ to _CI/CD workflow_ in GitLab 14.9. @@ -64,7 +64,7 @@ Authorization configuration can take one or two minutes to propagate. To authorize the agent to access the GitLab project where you keep Kubernetes manifests: -1. On the top bar, select **Main menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `projects` attribute. 1. For the `id`, add the path to the project. Do not wrap the path in quotation marks. @@ -89,7 +89,7 @@ Choose the context to run `kubectl` commands from your CI/CD scripts. To authorize the agent to access all of the GitLab projects in a group or subgroup: -1. On the top bar, select **Main menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `groups` attribute. 1. For the `id`, add the path: diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md index 98840080716..f0a681c1a5c 100644 --- a/doc/user/clusters/agent/gitops/flux.md +++ b/doc/user/clusters/agent/gitops/flux.md @@ -13,9 +13,13 @@ You can use Flux to: - Reconcile code changes with your deployments. - Manage your Flux installation itself with a bootstrap. +You can use the agent for Kubernetes with Flux to: + +- Trigger immediate Git repository reconciliation. + To get started, see the [Flux installation documentation](https://fluxcd.io/flux/installation). -Support for Flux is in [Beta](../../../../policy/alpha-beta-support.md#beta). +Support for Flux is in [Beta](../../../../policy/experiment-beta-support.md#beta). ## Bootstrap installation @@ -34,3 +38,60 @@ write access to the source repositories. ## GitOps repository structure You should organize your repositories to meet the needs of your team. For detailed recommendations, see the Flux [repository structure documentation](https://fluxcd.io/flux/guides/repository-structure/). + +## Immediate Git repository reconciliation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1. + +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 +unnecessary pulls from GitLab. + +The agent for Kubernetes automatically detects Flux `GitRepository` objects that +reference GitLab projects in the instance the agent is connected to, +and configures a [`Receiver`](https://fluxcd.io/flux/components/notification/receiver/) for the instance. +When the agent for Kubernetes detects a `git push`, the `Receiver` is triggered +and Flux reconciles the cluster with any changes to the repository. + +To use immediate Git repository reconciliation, you must have a Kubernetes cluster that runs: + +- The agent for Kubernetes. +- Flux `source-controller` and `notification-controller`. + +Immediate Git repository reconciliation can reduce the time between a push and reconciliation, +but it doesn't guarantee that every `git push` event is received. You should still set +[`GitRepository.spec.interval`](https://fluxcd.io/flux/components/source/gitrepositories/#interval) +to an acceptable duration. + +### Custom webhook endpoints + +When the agent for Kubernetes calls the `Receiver` webhook, +the agent defaults to `http://webhook-receiver.flux-system.svc.cluster.local`, +which is also the default URL set by a Flux bootstrap installation. To configure a custom +endpoint, set `flux.webhook_receiver_url` to a URL that the agent can resolve. For example: + +```yaml +flux: + webhook_receiver_url: http://webhook-receiver.another-flux-namespace.svc.cluster.local +``` + +There is special handing for +[service proxy URLs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster-services/) configured +in this format: `/api/v1/namespaces/[^/]+/services/[^/]+/proxy`. For example: + +```yaml +flux: + webhook_receiver_url: /api/v1/namespaces/flux-system/services/http:webhook-receiver:80/proxy +``` + +In these cases, the agent for Kubernetes uses the available Kubernetes configuration +and context to connect to the API endpoint. +You can use this if you run an agent outside a cluster +and you haven't [configured an `Ingress`](https://fluxcd.io/flux/guides/webhook-receivers/#expose-the-webhook-receiver) +for the Flux notification controller. + +WARNING: +You should configure only trusted service proxy URLs. +When you provide a service proxy URL, +the agent for Kubernetes sends typical Kubernetes API requests which include +the credentials necessary to authenticate with the API service. diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index bdb772ac14e..c6c9ed9e373 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -6,31 +6,28 @@ info: A tutorial using Flux # Tutorial: Set up Flux for GitOps **(FREE)** -This tutorial teaches you how to set up Flux for GitOps. You'll set up a sample project, -complete a bootstrap Flux installation, and authenticate your installation with a -[project deploy token](../../../project/deploy_tokens/index.md). - -You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). -It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. +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. To set up Flux for GitOps: 1. [Create a personal access token](#create-a-personal-access-token) -1. [Create the Flux repository](#create-the-flux-repository) -1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) -1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests) -1. [Verify your configuration](#verify-your-configuration) +1. [Complete a bootstrap installation](#complete-a-bootstrap-installation) +1. [Register `agentk`](#register-agentk) +1. [Install `agentk`](#install-agentk) +1. [Deploy an example project](#deploy-an-example-project) Prerequisites: -- You must have a Kubernetes cluster running. +- You must have a Kubernetes cluster you can access locally with `kubectl`. +- You must [install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). Be sure to install Flux v2 or higher. ## Create a personal access token -To authenticate with the Flux CLI, you must create a personal access token -with the `api` scope: +To authenticate with the Flux CLI, create a personal access token with +the `api` scope: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Enter a name and optional expiry date for the token. @@ -39,154 +36,172 @@ with the `api` scope: You can also use a [project](../../../project/settings/project_access_tokens.md) or [group access token](../../../group/settings/group_access_tokens.md) with the `api` scope. -## Create the Flux repository +## Complete a bootstrap installation -Create a Git repository, install Flux, and authenticate Flux with your repo: +In this section, you'll bootstrap Flux into an empty GitLab repository with the +[`flux bootstrap`](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise) +command. -1. Make sure your `kubectl` is configured to access your cluster. -1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). You must install Flux v2 or higher. -1. In GitLab, create a new empty project called `flux-config`. -1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your personal access token. - For example, `export GITLAB_TOKEN=<personal-access-token>`. -1. Run the `bootstrap` command. The exact command depends on whether you are - creating the Flux repository under a GitLab user, group, or subgroup. For more information, - see the [Flux bootstrap documentation](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise). +To bootstrap a Flux installation: - In this tutorial, you're working with a public project in a subgroup. The bootstrap command looks like this: +- Run the `flux bootstrap gitlab` command. For example: - ```shell - flux bootstrap gitlab \ - --owner=gitlab-org/configure/examples/flux \ - --repository=flux-config \ - --branch=main \ - --path=clusters/my-cluster \ - --deploy-token-auth - ``` + ```shell + flux bootstrap gitlab \ + --owner=example-org \ + --repository=my-repository \ + --branch=master \ + --path=clusters/testing \ + --deploy-token-auth + ``` - This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository `flux-config`. - The command also automatically creates the project deploy token required to access the `flux-config` repository. +The bootstrap script does the following: -Great work! You now have a repository bootstrapped with a Flux configuration. Any updates to your repository are automatically synced to the cluster. +1. Creates a deploy token and saves it as a Kubernetes `secret`. +1. Creates an empty GitLab project, if the project specified by `--repository` doesn't exist. +1. Generates Flux definition files for your project. +1. Commits the definition files to the specified branch. +1. Applies the definition files to your cluster. -## Create the Kubernetes manifest repository +After you run the script, Flux will be ready to manage itself and any other resources +you add to the GitLab project and path. -Next, create a repository for your Kubernetes manifests: +The rest of this tutorial assumes your path is `clusters/testing`. -1. In GitLab, create a new repository called `web-app-manifests`. -1. Add a file to `web-app-manifests` named `nginx-deployment.yaml` with the following contents: +### Upgrade Flux - ```yaml - apiVersion: apps/v1 +You might need to upgrade Flux some time after you install it. To do so: + +- Rerun the `flux bootstrap gitlab` command. + +## Register `agentk` + +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. + +## Install `agentk` + +Next, use Flux to create a namespace for `agentk` and install it in your cluster. + +This tutorial uses the namespace `gitlab` for `agentk`. - kind: Deployment +To install `agentk`: +1. Commit and push the following file to `clusters/testing/namespace-gitlab.yaml`: + + ```yaml + apiVersion: v1 + kind: Namespace metadata: - name: nginx-deployment - labels: - app: nginx - spec: - replicas: 3 - selector: - matchLabels: - app: nginx - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - ports: - - containerPort: 80 + name: gitlab ``` -1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the `read_repository` scope. -1. Store your deploy token username and password somewhere safe. -1. In Flux CLI, create a secret with your deploy token and point the secret to the new repository. For example: +1. Apply the agent registration token as a secret in the cluster: ```shell - flux create secret git flux-deploy-authentication \ - --url=https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests \ - --namespace=default \ - --username=<token-user-name> \ - --password=<token-password> + kubectl create secret generic gitlab-agent-token -n gitlab --from-literal=token=YOUR-TOKEN-HERE ``` -1. To check if your secret was generated successfully, run: + Although this step does not follow GitOps principles, it simplifies configuration for new Flux users. + For a proper GitOps setup, you should use a secret management solution. See the [Flux documentation](https://fluxcd.io/flux/guides). - ```shell - kubectl -n default get secrets flux-deploy-authentication -o yaml +1. Commit and push the following file to `clusters/testing/agentk.yaml`, replacing the values of + `.spec.values.config.kasAddress` and `.spec.values.config.secretName` with your saved `kas` address and secret `name`: + + ```yaml + --- + apiVersion: source.toolkit.fluxcd.io/v1beta2 + kind: HelmRepository + metadata: + labels: + app.kubernetes.io/component: agentk + app.kubernetes.io/created-by: gitlab + app.kubernetes.io/name: agentk + app.kubernetes.io/part-of: gitlab + name: gitlab-agent + namespace: gitlab + spec: + interval: 1h0m0s + url: https://charts.gitlab.io + --- + apiVersion: helm.toolkit.fluxcd.io/v2beta1 + kind: HelmRelease + metadata: + name: gitlab-agent + namespace: gitlab + spec: + chart: + spec: + chart: gitlab-agent + sourceRef: + kind: HelmRepository + name: gitlab-agent + namespace: gitlab-agent + interval: 1h0m0s + values: + config: + kasAddress: "wss://kas.gitlab.example.com" + secretName: "gitlab-agent-token" ``` - Under `data`, you should see base64-encoded values associated with your token username and password. +1. To verify that `agentk` is installed and running in the cluster, run the following command: -Congratulations! You now have a manifest repository, a deploy token, and a secret generated directly on your cluster. + ```shell + kubectl -n gitlab get pods + ``` + +Great work! You've successfully set up Flux with `agentk`. You can repeat the steps from this section +to deploy more applications from this project. In the next section, we'll discuss how to scale Flux across projects. -## Configure Flux to sync your manifests +## Deploy an example project -Next, tell `flux-config` to sync with the `web-app-manifests` repository. +You can scale Flux deployments across multiple GitLab projects by adding a Flux `GitRepository` and `Kustomization` that points to another project. +You can use this feature to store manifests related to a particular GitLab group in that group. -To do so, create a [`GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) resource: +To demonstrate, deploy an `nginx` application and point Flux at it: -1. Clone the `flux-config` repo to your machine. -1. In your local clone of `flux-config`, add the `GitRepository` file `clusters/my-cluster/web-app-manifests-source.yaml`: +1. Commit and push the following file to `clusters/testing/example-nginx-app.yaml`: ```yaml --- - apiVersion: source.toolkit.fluxcd.io/v1beta2 + apiVersion: source.toolkit.fluxcd.io/v1 kind: GitRepository metadata: - name: web-app-manifests - namespace: default + name: example-nginx-app + namespace: flux-system spec: interval: 1m0s ref: branch: main secretRef: - name: flux-deploy-authentication - url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests - ``` - - This file uses `secretRef` to refer back to the deploy token secret you created in the last step. - -1. In your local clone of `flux-config`, add the `GitRepository` file `clusters/my-cluster/web-app-manifests-kustomization.yaml`: - - ```yaml + name: example-nginx-app + url: https://gitlab.com/gitlab-examples/ops/gitops-demo/example-mini-flux-deployment.git --- - apiVersion: kustomize.toolkit.fluxcd.io/v1beta2 + apiVersion: kustomize.toolkit.fluxcd.io/v1 kind: Kustomization metadata: - name: nginx-source-kustomization - namespace: default + name: example-nginx-app + namespace: flux-system spec: - interval: 1m0s - path: ./ + interval: 10m0s + path: ./manifests prune: true sourceRef: kind: GitRepository - name: web-app-manifests - namespace: default - targetNamespace: default + name: example-nginx-app ``` - This file adds a [`Kustomization`](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests from - `web-app-manifests` with `kustomize`. - -1. Commit the new files and push. +1. To verify that the application was deployed correctly and `agentk` is running, run the following command: -## Verify your configuration - -You should see a newly created `nginx-deployment` pod in your cluster. - -To check whether the `nginx-deployment` pod is running in the default namespace, run the following: - -```shell -kubectl -n default get pods -n default -``` + ```shell + kubectl -n example-nginx get pods + ``` -If you want to see the deployment sync again, try updating the number of replicas in the -`nginx-deployment.yaml` file and push to your `main` branch. If all is working well, it -should sync to the cluster. +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) +and save it as a Flux secret. Be sure to save the namespace and secret name. -Excellent work! You've successfully set up a complete Flux project. +Congratulations! You have successfully scaled Flux to multiple groups and projects. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index ccb3a346903..8b1a55bc7bd 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -52,9 +52,12 @@ Use this workflow: This workflow has a weaker security model and is not recommended for production deployments. -## GitLab agent for Kubernetes supported cluster versions +## Supported Kubernetes versions for GitLab features -The agent for Kubernetes supports the following Kubernetes versions. You can upgrade your +GitLab supports the following Kubernetes versions. If you want to run +GitLab in a Kubernetes cluster, you might need a different version of Kubernetes. +GitLab in a Kubernetes cluster, you might need [a different version of Kubernetes](https://docs.gitlab.com/charts/installation/cloud/index.html). +You can upgrade your Kubernetes version to a supported version at any time: - 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 1bcbb42fc8e..76fcc73504c 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -29,7 +29,7 @@ Before you can install the agent in your cluster, you need: To install the agent in your cluster: -1. Optional. [Create an agent configuration file](#create-an-agent-configuration-file). +1. [Create an agent configuration file](#create-an-agent-configuration-file). 1. [Register the agent with GitLab](#register-the-agent-with-gitlab). 1. [Install the agent in your cluster](#install-the-agent-in-the-cluster). @@ -44,8 +44,7 @@ For configuration settings, the agent uses a YAML file in the GitLab project. Yo - You use [a GitOps workflow](../gitops.md#gitops-workflow-steps). - You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent. - -Otherwise it is optional. +- You [allow specific project or group members to access Kubernetes](../user_access.md). To create an agent configuration file: @@ -58,14 +57,12 @@ To create an agent configuration file: - Start with an alphanumeric character. - End with an alphanumeric character. -1. In the repository, in the default branch, create this directory at the root: +1. In the repository, in the default branch, create an agent configuration file at the root: ```plaintext - .gitlab/agents/<agent-name> + .gitlab/agents/<agent-name>/config.yaml ``` -1. In the directory, create a `config.yaml` file. Ensure the filename ends in `.yaml`, not `.yml`. - You can leave the file blank for now, and [configure it](#configure-your-agent) later. ### Register the agent with GitLab @@ -83,10 +80,10 @@ Prerequisites: You must register an agent before you can install the agent in your cluster. To register an agent: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. If you have an [agent configuration file](#create-an-agent-configuration-file), it must be in this project. Your cluster manifest files should also be in this project. -1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. +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](#create-an-agent-configuration-file), select it from the list. @@ -144,7 +141,7 @@ When [KAS](../../../../administration/clusters/kas.md) is behind a self-signed c you can set the value of `config.caCert` to the certificate. For example: ```shell -helm update --install gitlab-agent gitlab/gitlab-agent \ +helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --set-file config.caCert=my-custom-ca.pem ``` diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 531dac20fb6..9c0733d66b7 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -239,4 +239,4 @@ When you install the agent, you might encounter an error that states: Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): unclosed action ``` -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#gitlab-agent-for-kubernetes-supported-cluster-versions). +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). diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md new file mode 100644 index 00000000000..be3f88d072e --- /dev/null +++ b/doc/user/clusters/agent/user_access.md @@ -0,0 +1,152 @@ +--- +stage: Deploy +group: Environments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Grant users Kubernetes access (Beta) **(FREE)** + +> [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). + +As an administrator of Kubernetes clusters in an organization, you can grant Kubernetes access to members +of a specific project or group. + +Granting access also activates the Dashboard for Kubernetes for a project or group. + +## Configure Kubernetes access + +Configure access when you want to grant users access +to a Kubernetes cluster. + +Prerequisites: + +- The agent for Kubernetes is installed in the Kubernetes cluster. +- You must have the Developer role or higher. + +To configure access: + +- In the agent configuration file, define a `user_access` keyword with the following parameters: + + - `projects`: A list of projects whose members should have access. + - `groups`: A list of groups whose members should have access. + - `access_as`: Required. For plain access, the value is `{ agent: {...} }`. + +After you configure access, requests are forwarded to the API server using +the agent service account. +For example: + +```yaml +# .gitlab/agents/my-agent/config.yaml + +user_access: + access_as: + agent: {} + projects: + - id: group-1/project-1 + - id: group-2/project-2 + groups: + - id: group-2 + - id: group-3/subgroup +``` + +## Configure access with user impersonation **(PREMIUM)** + +You can grant access to a Kubernetes cluster and transform +requests into impersonation requests for authenticated users. + +Prerequisites: + +- The agent for Kubernetes is installed in the Kubernetes cluster. +- You must have the Developer role or higher. + +To configure access with user impersonation: + +- In the agent configuration file, define a `user_access` keyword with the following parameters: + + - `projects`: A list of projects whose members should have access. + - `groups`: A list of groups whose members should have access. + - `access_as`: Required. For user impersonation, the value is `{ user: {...} }`. + +After you configure access, requests are transformed into impersonation requests for +authenticated users. + +### User impersonation workflow + +The installed `agentk` impersonates the given users as follows: + +- `UserName` is `gitlab:user:<username>` +- `Groups` is: + - `gitlab:user`: Common to all requests coming from GitLab users. + - `gitlab:project_role:<project_id>:<role>` for each role in each authorized project. + - `gitlab:group_role:<group_id>:<role>` for each role in each authorized group. +- `Extra` carries additional information about the request: + - `agent.gitlab.com/id`: The agent ID. + - `agent.gitlab.com/username`: The username of the GitLab user. + - `agent.gitlab.com/config_project_id`: The agent configuration project ID. + - `agent.gitlab.com/access_type`: One of `personal_access_token`, + `oidc_id_token`, or `session_cookie`. + +Only projects and groups directly listed in the under `user_access` in the configuration +file are impersonated. For example: + +```yaml +# .gitlab/agents/my-agent/config.yaml + +user_access: + access_as: + user: {} + projects: + - id: group-1/project-1 # group_id=1, project_id=1 + - id: group-2/project-2 # group_id=2, project_id=2 + groups: + - id: group-2 # group_id=2 + - id: group-3/subgroup # group_id=3, group_id=4 +``` + +In this configuration: + +- If a user is a member of only `group-1`, they receive + only the Kubernetes RBAC groups `gitlab:project_role:1:<role>`. +- If a user is a member of `group-2`, they receive both Kubernetes RBAC groups: + - `gitlab:project_role:2:<role>`, + - `gitlab:group_role:2:<role>`. + +### RBAC authorization + +Impersonated requests require `ClusterRoleBinding` or `RoleBinding` to identify the resource permissions +inside Kubernetes. See [RBAC authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +for the appropriate configuration. + +For example, if you allow maintainers in `awesome-org/deployment` project (ID: 123) to read the Kubernetes workloads, +you must add a `ClusterRoleBinding` resource to your Kubernetes configuration: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: my-cluster-role-binding +roleRef: + name: view + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io +subjects: + - name: gitlab:project_role:123:maintainer + kind: Group +``` + +## Related topics + +- [Architectural blueprint](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kubernetes_user_access.md) +- [Dashboard for Kubernetes](https://gitlab.com/groups/gitlab-org/-/epics/2493) + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index a71eea82df5..74676e31d22 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -15,11 +15,11 @@ You can also configure your agent so the vulnerabilities are displayed with othe ## Enable operational container scanning You can use operational container scanning to scan container images in your cluster for security vulnerabilities. You -can enable the scanner to run on a cadence as configured via the agent, or setup scan execution policies within a +can enable the scanner to run on a cadence as configured via the `agent config`, or setup `scan execution policies` within a project that houses the agent. NOTE: -In GitLab 15.0 and later, you do not need to install Starboard operator in the Kubernetes cluster. +If both `agent config` and `scan execution policies` are configured, the configuration from `scan execution policy` takes precedence. ### Enable via agent configuration @@ -56,7 +56,7 @@ container_scanning: - kube-system ``` -## Enable via scan execution policies +### Enable via scan execution policies To enable scanning of all images within your Kubernetes cluster via scan execution policies, we can use the [scan execution policy editor](../../application_security/policies/scan-execution-policies.md#scan-execution-policy-editor) @@ -96,12 +96,41 @@ The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock You can view the complete schema within the [scan execution policy documentation](../../application_security/policies/scan-execution-policies.md#scan-execution-policies-schema). +## Configure scanner resource requirements + +By default the scanner pod's default resource requirements are: + +```yaml +requests: + cpu: 100m + memory: 100Mi +limits: + cpu: 500m + memory: 500Mi +``` + +You can customize it with a `resource_requirements` field. + +```yaml +container_scanning: + resource_requirements: + requests: + cpu: 200m + memory: 200Mi + limits: + cpu: 700m + memory: 700Mi +``` + +NOTE: +Resource requirements can only be set up using the agent configuration. If you enabled `Operational Container Scanning` through `scan execution policies`, you would need to define the resource requirements within the agent configuration file. + ## View cluster vulnerabilities To view vulnerability information in GitLab: -1. On the top bar, select **Main menu > Projects** and find the project that contains the agent configuration file. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the agent configuration file. +1. Select **Operate > Kubernetes clusters**. 1. Select the **Agent** tab. 1. Select an agent to view the cluster vulnerabilities. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 2d54f67724e..8bf9ac7cf06 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -18,9 +18,9 @@ Prerequisite: To view the list of agents: -1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains your agent configuration file. You cannot view registered agents from a project that does not contain the agent configuration file. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Operate > Kubernetes clusters**. 1. Select **Agent** tab to view clusters connected to GitLab through the agent. On this page, you can view: @@ -30,6 +30,22 @@ On this page, you can view: - The version of `agentk` installed on your cluster. - The path to each agent configuration file. +## View shared agents + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395498) in GitLab 16.1. + +In addition to the agents owned by your project, you can also view agents shared with the +[`ci_access`](ci_cd_workflow.md) and [`user_access`](user_access.md) keywords. Once an agent +is shared with a project, it automatically appears in the project agent tab. + +To view the list of shared agents: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Kubernetes clusters**. +1. Select the **Agent** tab. + +The list of shared agents and their clusters are displayed. + ## View an agent's activity information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6. @@ -38,8 +54,8 @@ The activity logs help you to identify problems and get the information you need for troubleshooting. You can see events from a week before the current date. To view an agent's activity: -1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains your agent configuration file. +1. Select **Operate > Kubernetes clusters**. 1. Select the agent you want to see activity for. The activity list includes: @@ -91,12 +107,15 @@ For more information about debugging, see [troubleshooting documentation](troubl > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327152) in GitLab 14.9. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336641) in GitLab 14.10, the agent token can be revoked from the UI. +> - Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030) in GitLab 16.1. + +An agent can have only two active tokens at one time. To reset the agent token without downtime: 1. Create a new token: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Operate > Kubernetes clusters**. 1. Select the agent you want to create a token for. 1. On the **Access tokens** tab, select **Create token**. 1. Enter token's name and description (optional) and select **Create token**. @@ -117,8 +136,8 @@ clean up those resources manually. To remove an agent from the UI: -1. On the top bar, select **Main menu > Projects** and find the project that contains the agent configuration file. -1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the agent configuration file. +1. Select **Operate > Kubernetes clusters**. 1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Delete agent**. diff --git a/doc/user/clusters/img/kubecost_v13_5.png b/doc/user/clusters/img/kubecost_v13_5.png Binary files differdeleted file mode 100644 index a93e2531b16..00000000000 --- a/doc/user/clusters/img/kubecost_v13_5.png +++ /dev/null diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 0ad3fdbef2e..ff6cf6bb1a8 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -61,7 +61,10 @@ To associate a cluster management project with your cluster: **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Main menu > Admin > Kubernetes**. + - [Instance-level cluster](../instance/clusters/index.md): + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Kubernetes**. 1. Expand **Advanced settings**. 1. From the **Cluster management project** dropdown list, select the cluster management project you created in the previous step. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 4b6c8dcac4c..f6bcff0481a 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -45,8 +45,7 @@ If you have already configured the agent and connected a cluster with GitLab: To create a project from the cluster management project template: -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. From the list of templates, next to **GitLab Cluster Management**, select **Use template**. 1. Enter the project details. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index d04aeec066f..ab80fbbba8e 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -35,14 +35,16 @@ When you select a row in the compliance report, a drawer appears that provides: ### 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 top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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: @@ -50,6 +52,12 @@ You can sort the compliance report on: - 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 @@ -142,8 +150,8 @@ If the commit has a related merge commit, then the following are also included: To generate the Chain of Custody report: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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. @@ -158,8 +166,8 @@ details for the provided commit SHA. To generate a commit-specific Chain of Custody report: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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**. @@ -189,8 +197,8 @@ Prerequisites: To view the compliance frameworks report: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance 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 @@ -206,16 +214,16 @@ Prerequisites: To apply a compliance framework to one project in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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. 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 top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. @@ -235,15 +243,15 @@ Prerequisites: To remove a compliance framework from one project in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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. 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 top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. @@ -264,8 +272,8 @@ Prerequisites: To export a report of compliance frameworks on projects in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security and Compliance > Compliance 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. 1. On the Frameworks tab, select the **Export as CSV** action in the top right corner @@ -277,8 +285,8 @@ A report is compiled and delivered to your email inbox as an attachment. To filter the list of compliance frameworks: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance 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. 1. In the search field: 1. Select the attribute you want to filter by. diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index 860c2008021..96a4a08249a 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -24,6 +24,16 @@ The following video provides an overview of these policies. <iframe src="https://www.youtube-nocookie.com/embed/34qBQ9t8qO8" frameborder="0" allowfullscreen> </iframe> </figure> +## Prerequisites to creating a new license approval policy + +License approval policies rely on the output of a dependency scanning job to verify that requirements have been met. If dependency scanning has not been properly configured, and therefore no dependency scanning jobs ran related to an open MR, the policy has no data with which to verify the requirements. When security policies are missing data for evaluation, they fail closed and assume the merge request could contain vulnerabilities. + +To ensure enforcement of your policies, you should enable dependency scanning on your target development projects. You can achieve this a few different ways: + +- Create a global [scan execution policy](../application_security/policies/scan-execution-policies.md) that enforces Dependency Scanning to run in all target development projects. +- Use a [Compliance Pipeline](../../user/group/compliance_frameworks.md#compliance-frameworks) to define a Dependency Scanning job that is enforced on projects enforced by a given Compliance Framework. +- Work with development teams to configure [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) in each of their project's `.gitlab-ci.yml` files or enable by using the [Security Configuration panel](../application_security/configuration/index.md). + ## Create a new license approval policy Create a license approval policy to enforce license compliance. @@ -31,8 +41,8 @@ Create a license approval policy to enforce license compliance. To create a license approval policy: 1. [Link a security policy project](../application_security/policies/index.md#managing-the-linked-security-policy-project) to your development group, subgroup, or project (the Owner role is required). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Policies**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Policies**. 1. Create a new [Scan Result Policy](../application_security/policies/scan-result-policies.md). 1. In your policy rule, select **License scanning**. diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md index 832f1007a91..22defd593cd 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -23,7 +23,7 @@ Licenses not in the SPDX list are reported as "Unknown". License information can Prerequisites: -- Enable [Synchronization with the GitLab License Database](../../admin_area/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in Admin Area for the GitLab instance. +- On GitLab self-managed only, enable [Synchronization with the GitLab License Database](../../admin_area/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in Admin Area for the GitLab instance. On GitLab SaaS this step has already been completed. - Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration) and ensure that its prerequisites are met. diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 54e87118361..c81cf6762e3 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -36,8 +36,8 @@ you must enable CRM features for the subgroup. To enable customer relations management in a group or subgroup: -1. On the top bar, select **Main menu > Groups** and find your group or subgroup. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group or subgroup. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Customer relations is enabled**. 1. Select **Save changes**. @@ -52,8 +52,8 @@ Prerequisites: To view a group's contacts: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Contacts**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer contacts**. ![Contacts list](crm_contacts_v14_10.png) @@ -65,8 +65,8 @@ Prerequisites: To create a contact: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Contacts**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer contacts**. 1. Select **New contact**. 1. Complete all required fields. 1. Select **Create new contact**. @@ -82,8 +82,8 @@ Prerequisites: To edit an existing contact: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Contacts**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer contacts**. 1. Next to the contact you wish to edit, select **Edit** (**{pencil}**). 1. Edit the required fields. 1. Select **Save changes**. @@ -100,8 +100,8 @@ Each contact can be in one of two states: To change the state of a contact: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Contacts**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer contacts**. 1. Next to the contact you wish to edit, select **Edit** (**{pencil}**). 1. Select or clear the **Active** checkbox. 1. Select **Save changes**. @@ -116,8 +116,8 @@ Prerequisites: To view a group's organizations: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Organizations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer organizations**. ![Organizations list](crm_organizations_v14_10.png) @@ -129,8 +129,8 @@ Prerequisites: To create an organization: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Organizations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer organizations**. 1. Select **New organization**. 1. Complete all required fields. 1. Select **Create new organization**. @@ -146,8 +146,8 @@ Prerequisites: To edit an existing organization: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Organizations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer organizations**. 1. Next to the organization you wish to edit, select **Edit** (**{pencil}**). 1. Edit the required fields. 1. Select **Save changes**. @@ -168,8 +168,8 @@ Prerequisites: To view a contact's issues, select a contact from the issue sidebar, or: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Contacts**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer contacts**. 1. Next to the contact whose issues you wish to view, select **View issues** (**{issues}**). ### View issues linked to an organization @@ -180,8 +180,8 @@ Prerequisites: To view an organization's issues: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Customer relations > Organizations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Customer organizations**. 1. Next to the organization whose issues you wish to view, select **View issues** (**{issues}**). ### View contacts linked to an issue diff --git a/doc/user/discussions/img/reply_to_comment_button.png b/doc/user/discussions/img/reply_to_comment_button.png Binary files differdeleted file mode 100644 index d327d1c3e27..00000000000 --- a/doc/user/discussions/img/reply_to_comment_button.png +++ /dev/null diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 096b4dc2cc5..03b48fd42b6 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -18,7 +18,7 @@ GitLab encourages communication through comments, threads, and Two types of comments are available: - A standard comment. -- A comment in a thread, which can be [resolved](#resolve-a-thread). +- A comment in a thread, which can be [resolved](../project/merge_requests/index.md#resolve-a-thread). In a comment, you can enter [Markdown](../markdown.md) and use [quick actions](../project/quick_actions.md). @@ -51,9 +51,25 @@ You can quickly see which comments involve you, because mentions for yourself (the user who is signed in) are highlighted in a different color. -Avoid mentioning `@all` in issues and merge requests. It sends an email notification -to all members of that project's parent group, not only the participants of the project. -It might be interpreted as spam. +### Mentioning all members + +> [Flag](../../administration/feature_flags.md) named `disable_all_mention` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110586) in GitLab 16.1. Disabled by default. [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/18442). + +FLAG: +On self-managed GitLab, by default this flag is not enabled. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) +named `disable_all_mention`. +On GitLab.com, this flag is enabled. + +When this feature flag is enabled, typing `@all` in comments and descriptions +results in plain text instead of a mention. +When you disable this feature, existing `@all` mentions in the Markdown texts are not affected +and remain as links. Only future `@all` mentions appear as plain text. + +Avoid mentioning `@all` in comments and descriptions. +When you do it, you don't only mention the participants of the project, issue, or merge request, +but to all members of that project's parent group. +All these users receive an email notification and a to-do item. It might be interpreted as spam. + Notifications and mentions can be disabled in [a group's settings](../group/manage.md#disable-email-notifications). @@ -95,29 +111,6 @@ it's converted to a link in the context of the merge request. For example, `28719b171a056960dfdc0012b625d0b47b123196` becomes `28719b17` that links to `https://gitlab.example.com/example-group/example-project/-/merge_requests/12345/diffs?commit_id=28719b171a056960dfdc0012b625d0b47b123196`. -## Add a comment to a commit - -You can add comments and threads to a particular commit. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Commits**. -1. Below the commits, in the **Comment** field, enter a comment. -1. Select **Comment** or select the down arrow (**{chevron-down}**) to select **Start thread**. - -WARNING: -Threads created this way are lost if the commit ID changes after a -force push. - -## Add a comment to an image - -In merge requests and commit detail views, you can add a comment to an image. -This comment can also be a thread. - -1. Hover your mouse over the image. -1. Select the location where you want to comment. - -An icon is displayed on the image and a comment field is displayed. - ## Reply to a comment by sending email If you have ["reply by email"](../../administration/reply_by_email.md) configured, @@ -236,8 +229,6 @@ To compare the changes, select **Compare with previous version**. ## Assign an issue to the commenting user -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. - You can assign an issue to a user who made a comment. 1. In the comment, select the **More Actions** (**{ellipsis_v}**) menu. @@ -256,9 +247,7 @@ Prerequisites: To create a thread by replying to a comment: -1. In the upper-right corner of the comment, select **Reply to comment** (**{comment}**). - - ![Reply to comment button](img/reply_to_comment_button.png) +1. In the upper-right corner of the comment, select **Reply to comment** (**{reply}**). The reply section is displayed. @@ -286,75 +275,3 @@ To create a thread: A threaded comment is created. ![Thread comment](img/discussion_comment.png) - -## Resolve a thread - -> Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. - -In a merge request, you can resolve a thread when you want to finish a conversation. - -Prerequisites: - -- You must have at least the Developer role - or be the author of the change being reviewed. -- Resolvable threads can be added only to merge requests. It doesn't work - for comments in issues, commits, or snippets. - -To resolve a thread: - -1. Go to the thread. -1. Do one of the following: - - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**). - - Below the last reply, in the **Reply** field, select **Resolve thread**. - - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. - -At the top of the page, the number of unresolved threads is updated: - -![Count of unresolved threads](img/unresolved_threads_v15_4.png) - -### Move all unresolved threads in a merge request to an issue - -If you have multiple unresolved threads in a merge request, you can -create an issue to resolve them separately. In the merge request, at the top of the page, -select the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Resolve all with new issue**: - -![Open new issue for all unresolved threads](img/create_new_issue_v15_4.png) - -All threads are marked as resolved, and a link is added from the merge request to -the newly created issue. - -### Move one unresolved thread in a merge request to an issue - -If you have one specific unresolved thread in a merge request, you can -create an issue to resolve it separately. In the merge request, under the last reply -to the thread, next to **Resolve thread**, select **Create issue to resolve thread** (**{issue-new}**): - -![Create issue for thread](img/new-issue-one-thread_v14_3.png) - -The thread is marked as resolved, and a link is added from the merge request to -the newly created issue. - -### Prevent merge unless all threads are resolved - -You can prevent merge requests from being merged until all threads are -resolved. When this setting is enabled, the **Unresolved threads** counter in a merge request -is shown in orange when at least one thread remains unresolved. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. -1. In the **Merge checks** section, select the **All threads must be resolved** checkbox. -1. Select **Save changes**. - -### Automatically resolve threads in a merge request when they become outdated - -You can set merge requests to automatically resolve threads when lines are modified -with a new push. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. -1. In the **Merge options** section, select - **Automatically resolve merge request diff threads when they become outdated**. -1. Select **Save changes**. - -Threads are now resolved if a push makes a diff section outdated. -Threads on lines that don't change and top-level resolvable threads are not resolved. diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index ffeaaa8c591..36f698daf81 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -11,7 +11,7 @@ Enterprise users have user accounts that are administered by an organization tha has purchased a [GitLab subscription](../../subscriptions/index.md). Enterprise users are identified by the [**Enterprise** badge](../project/badges.md) -next to their names on the [Members list](../group/manage.md#filter-and-sort-members-in-a-group). +next to their names on the [Members list](../group/index.md#filter-and-sort-members-in-a-group). ## Provision an enterprise user @@ -25,7 +25,8 @@ A user account is considered an enterprise account when: A user can also [manually connect an identity provider (IdP) to a GitLab account whose email address matches the subscribing organization's domain](../group/saml_sso/index.md#link-saml-to-your-existing-gitlabcom-account). By selecting **Authorize** when connecting these two accounts, the user account with the matching email address is classified as an enterprise user. However, this -user account does not have an **Enterprise** badge in GitLab. +user account does not have an **Enterprise** badge in GitLab, and a group Owner cannot +disable the user's two-factor authentication. Although a user can be a member of more than one group, each user account can be provisioned by only one group. As a result, a user is considered an enterprise @@ -43,11 +44,18 @@ Prerequisites: - A custom domain name `example.com` or subdomain `subdomain.example.com`. - Access to your domain's server control panel to set up a DNS `TXT` record to verify your domain's ownership. +- A project in the group. +- You must have the Owner role in the top-level group. Setting up a verified domain is similar to [setting up a custom domain on GitLab Pages](../project/pages/custom_domains_ssl_tls_certification/index.md). However, you must: -- Link the domain to a project. For more information on group-level domain verification, see [issue 5299](https://gitlab.com/groups/gitlab-org/-/epics/5299). -- Configure the DNS `TXT` record to verify the domain's ownership. +- Link the domain to a single project. +- Configure the `TXT` only in the DNS record to verify the domain's ownership. + +Domain verification is tied to the project you choose. A project is required because domain verification reuses the GitLab Pages verification feature, which requires a project. Domain verification applies at the top-level group and to all subgroups and projects nested under that top-level parent group. +A member in the chosen project with [at least the Maintainer role](../permissions.md#project-members-permissions) can modify or remove the domain verification. +If needed, you can create a new project to set up domain verification directly under your top-level group. This limits the ability to modify the domain verification to members with at least the Maintainer role. +For more information on group-level domain verification, see [epic 5299](https://gitlab.com/groups/gitlab-org/-/epics/5299). Steps: @@ -55,15 +63,21 @@ Steps: The custom domain must match the email domain exactly. For example, if your email is `username@example.com`, verify the `example.com` domain. -1. On the top bar, select **Main menu > Groups** and find your top group. -1. On the left sidebar, select **Settings > Domain Verification**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. Select **Settings > Domain Verification**. 1. In the upper-right corner, select **Add Domain**. 1. In **Domain**, enter the domain name. 1. In **Project**, link to a project. -1. Optional. In **Certificate**, switch the **Manually enter certificate information** toggle to add an SSL/TLS - certificate. You can also add the certificate and key later. +1. In **Certificate**: + - If you do not have or do not want to use an SSL certificate, leave **Automatic certificate management using Let's + Encrypt** selected. + - Optional. Turn on the **Manually enter certificate information** toggle to add an SSL/TLS certificate. You can also + add the certificate and key later. 1. Select **Add Domain**. +NOTE: +A valid certificate is not required for domain verification. You can ignore error messages regarding the certificate if you are not using GitLab Pages. + #### 2. Get a verification code After you create a new domain, the verification code prompts you. Copy the values from GitLab @@ -75,8 +89,8 @@ and paste them in your domain's control panel as a `TXT` record. After you have added all the DNS records: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Domain Verification**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Domain Verification**. 1. On the domain table row, Select **Retry verification** (**{retry}**). ![Verify your domain](../img/retry_domain_verification_v16_0.png) @@ -97,13 +111,14 @@ from the GitLab project. > - Once your domain has been verified, leave the verification record in place. Your domain is periodically reverified, and may be disabled if the record is removed. +> - A valid certificate is not required for domain verification. ### View domains in group To view all configured domains in your group: -1. On the top bar, select **Main menu > Groups** and find your top-level group. -1. On the left sidebar, select **Settings > Domain Verification**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your top-level group. +1. Select **Settings > Domain Verification**. You then see: @@ -127,8 +142,8 @@ Top-level group Owners can disable two-factor authentication (2FA) for enterpris To disable 2FA: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. 1. Find a user with the **Enterprise** and **2FA** badges. 1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**. @@ -149,3 +164,9 @@ A top-level group Owner can [set up verified domains to bypass confirmation emai A top-level group Owner can use the [group and project members API](../../api/members.md) to access users' information, including email addresses. + +## Troubleshooting + +### Cannot disable two-factor authentication for an enterprise user + +If an enterprise user does not have an **Enterprise** badge, a top-level group Owner cannot [disable or reset 2FA](#disable-two-factor-authentication) for that user. Instead, the Owner should tell the enterprise user to consider available [recovery options](../profile/account/two_factor_authentication.md#recovery-options). diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 181eb00bb50..410bdc4b5f5 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -27,7 +27,7 @@ Prerequisite: - You must have the Owner role for the group. -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. To view all members, select the **Seats** tab. 1. To remove a member, select **Remove user**. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index fae45e4b2d3..82d0bfb035a 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -438,6 +438,12 @@ See [non-configurable limits](../../security/rate_limits.md#non-configurable-lim for information on rate limits that are not configurable, and therefore also used on GitLab.com. +## GitLab.com-specific Gitaly RPC concurrency limits + +Per-repository Gitaly RPC concurrency and queuing limits are configured for different types of Git operations such as `git clone`. When these limits are exceeded, a `fatal: remote error: GitLab is currently unable to handle this request due to load` message is returned to the client. + +For administrator documentation, see [limit RPC concurrency](../../administration/gitaly/configure_gitaly.md#limit-rpc-concurrency). + ## GitLab.com logging We use [Fluentd](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#fluentd) @@ -462,7 +468,7 @@ and can't be configured on GitLab.com to expire. You can erase job logs ## GitLab.com at scale -In addition to the GitLab Enterprise Edition Omnibus install, GitLab.com uses +In addition to the GitLab Enterprise Edition Linux package install, GitLab.com uses the following applications and settings to achieve scale. All settings are publicly available, as [Kubernetes configuration](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com) or [Chef cookbooks](https://gitlab.com/gitlab-cookbooks). diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 50506d005b0..b7acded6720 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -46,8 +46,8 @@ configured by an administrator. To change the permitted Git access protocols for a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Choose the permitted protocols from **Enabled Git access protocols**. 1. Select **Save changes**. @@ -58,7 +58,7 @@ To change the permitted Git access protocols for a group: > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. To ensure only people from your organization can access particular resources, you can restrict access to groups by IP -address. This group-level setting applies to: +address. This top-level group setting applies to: - The GitLab UI, including subgroups, projects, and issues. It does not apply to GitLab Pages. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. @@ -71,8 +71,8 @@ Administrators can combine restricted access by IP address with To restrict group access by IP address: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. In the **Restrict access by IP address** text box, enter a list of IPv4 or IPv6 address ranges in CIDR notation. This list: @@ -112,8 +112,8 @@ You can prevent users with email addresses in specific domains from being added To restrict group access by domain: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. In the **Restrict membership by email** field, enter the domain names. 1. Select **Save changes**. @@ -156,8 +156,8 @@ If you prevent group sharing outside the hierarchy for the **Animals** group: To prevent sharing outside of the group's hierarchy: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select **Members cannot invite groups outside of `<group_name>` and its subgroups**. 1. Select **Save changes**. @@ -172,8 +172,8 @@ which can be confusing and difficult to control. To restrict the permission to invite project members to a single source, prevent a project from being shared with other groups: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Projects in `<group_name>` cannot be shared with other groups**. 1. Select **Save changes**. @@ -186,10 +186,8 @@ added to a project lose access when the setting is enabled. As a group Owner, you can prevent non-members from requesting access to your group. -1. On the top bar, **Main menu > Groups** and find your group. -1. Select **Your Groups**. -1. Find the group and select it. -1. From the left menu, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Clear the **Allow users to request access** checkbox. 1. Select **Save changes**. @@ -208,8 +206,8 @@ If even one is set to `true`, then the group does not allow outside forks. To prevent projects from being forked outside the group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Check **Prevent project forking outside current group**. 1. Select **Save changes**. @@ -233,8 +231,9 @@ The setting does not cascade. Projects in subgroups observe the subgroup configu To prevent members from being added to projects in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand the **Permissions and group features** section. 1. Under **Membership**, select **Users cannot be added to projects in this group**. 1. Select **Save changes**. @@ -282,15 +281,15 @@ To create group links via filter: LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. If LDAP synchronization +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Manage > Members**. If LDAP synchronization has granted a user a role with: - More permissions than the parent group membership, that user is displayed as having [direct membership](../project/members/index.md#display-direct-members) of the group. - The same or fewer permissions than the parent group membership, that user is displayed as having [inherited membership](../project/members/index.md#display-inherited-members) of the group. 1. Optional. If the user you want to edit is displayed as having inherited membership, - [filter the subgroup to show direct members](manage.md#filter-a-group) before + [filter the subgroup to show direct members](index.md#filter-a-group) before overriding LDAP user permissions. 1. In the row for the user you are editing, select the pencil (**{pencil}**) icon. 1. Select **Edit permissions** in the modal. @@ -318,6 +317,6 @@ If a parent group membership has the same or higher role than a subgroup, the listed on the subgroup members page, even if a [direct membership](../project/members/index.md#membership-types) on the group exists. -To view and update direct memberships, [filter the group to show direct members](manage.md#filter-a-group). +To view and update direct memberships, [filter the group to show direct members](index.md#filter-a-group). The need to filter members by type through a redesigned members page that lists both direct and inherited memberships is proposed in [issue 337539](https://gitlab.com/gitlab-org/gitlab/-/issues/337539#note_1277786161). diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 4c448d8e5c2..15fa5941dc2 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -21,8 +21,8 @@ your group, enabling you to use the same cluster across multiple projects. To view your group-level Kubernetes clusters: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Kubernetes**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Operate > Kubernetes**. ## Cluster management project @@ -89,8 +89,8 @@ your cluster, which can cause deployment jobs to fail. To clear the cache: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Kubernetes**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Operate > Kubernetes**. 1. Select your cluster. 1. Expand **Advanced settings**. 1. Select **Clear cluster cache**. diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 2fca8b7b678..47764b0c915 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -16,8 +16,8 @@ requirements or needs additional oversight. The label can optionally enforce Compliance frameworks are created on top-level groups. Group owners can create, edit, and delete compliance frameworks: -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. -1. On the left sidebar, select **Settings** > **General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. 1. Create, edit, or delete compliance frameworks. @@ -40,8 +40,8 @@ A compliance framework that is set to default has a **default** label. Group owners can set a compliance framework as default (or remove the setting): -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Compliance frameworks** section and locate the compliance framework to set (or remove) as default. 1. Select the vertical ellipsis (**{ellipsis_v}**) for the compliance frame and then select **Set default** (or **Remove default**). @@ -125,8 +125,8 @@ Therefore, communicate with project users about compliance pipeline configuratio To configure a compliance pipeline: -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. -1. On the left sidebar, select **Settings** > **General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. 1. In **Compliance pipeline configuration (optional)**, add the path to the compliance framework configuration. Use the `path/file.y[a]ml@group-name/project-name` format. For example: @@ -397,3 +397,22 @@ You could also have the following `.gitlab-ci.yml` configuration: This configuration doesn't overwrite the compliance pipeline and you get the following message: `take compliance action`. + +### Prefilled variables are not shown + +Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382857), +compliance pipelines in GitLab 15.3 and later can prevent +[prefilled variables](../../ci/pipelines/index.md#prefill-variables-in-manual-pipelines) +from appearing when manually starting a pipeline. + +To workaround this issue, use `ref: '$CI_COMMIT_SHA'` instead of `ref: '$CI_COMMIT_REF_NAME'` +in the `include:` statement that executes the individual project's configuration. + +The [example configuration](#example-configuration) has been updated with this change: + +```yaml +include: + - project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_SHA' +``` diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index b0347ba5caa..02f1e7f21e2 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -20,8 +20,8 @@ Use contribution analytics data visualizations to: To view contribution analytics: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Contribution**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Contribution analytics**. Three bar charts and a table illustrate the number of contributions made by each group member: diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 95d7ddb056e..cbab83dd61e 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -29,7 +29,7 @@ To set up custom project templates in a group, add the subgroup that contains th project templates to the group settings: 1. In the group, create a [subgroup](subgroups/index.md). -1. [Add projects to the new subgroup](manage.md#add-projects-to-a-group) as your templates. +1. [Add projects to the new subgroup](index.md#add-projects-to-a-group) as your templates. 1. In the left menu for the group, select **Settings > General**. 1. Expand **Custom project templates** and select the subgroup. diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 7105318e5df..7aa4695e58b 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group DevOps Adoption **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](../../../policy/alpha-beta-support.md#beta). +> - [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. > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. @@ -36,8 +36,8 @@ Prerequisite: To view DevOps Adoption: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > DevOps adoption** +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > DevOps adoption** ## DevOps Adoption categories @@ -80,8 +80,8 @@ twelve months. The chart only shows data from when you enabled DevOps Adoption f To view feature adoption over time: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > DevOps adoption**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > DevOps adoption**. 1. Select the **Overview** tab. Tooltips display information about the features tracked for individual months. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 6783e89779b..4a913c385a0 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -25,8 +25,8 @@ On the top of each list, you can see the number of epics in the list (**{epic}** To view an epic board: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Epics > Boards**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Epic boards**. ![GitLab epic board - Premium](img/epic_board_v15_10.png) @@ -38,8 +38,8 @@ Prerequisites: To create a new epic board: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Epics > Boards**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Epic boards**. 1. In the upper-left corner, select the dropdown list with the current board name. 1. Select **Create new board**. 1. Enter the new board's title. @@ -87,8 +87,8 @@ Prerequisites: To create a new list: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Epics > Boards**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Epic boards**. 1. In the upper-right corner, select **Create list**. 1. In the **New list** column expand the **Select a label** dropdown list and select the label to use as list scope. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 32454693d71..5d3bac4f895 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -19,6 +19,13 @@ Use epics: - To track when the work for the group of issues is targeted to begin and end. - To discuss and collaborate on feature ideas and scope at a high level. +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=kdE-yb6Puuo">GitLab Epics - Setting up your Organization with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/kdE-yb6Puuo" frameborder="0" allowfullscreen> </iframe> +</figure> + ## Relationships between epics and issues The possible relationships between epics and issues are: diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 98316188496..9436ff317a7 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -205,8 +205,8 @@ Prerequisites: To view epics in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Epics**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Epics**. ### Who can view an epic @@ -250,8 +250,8 @@ You can filter the list of epics by: To filter: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Epics**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Epics**. 1. Select the field **Search or filter results**. 1. From the dropdown list, select the scope or enter plain text to search by epic title or description. 1. Press <kbd>Enter</kbd> on your keyboard. The list is filtered. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 7f55bf56102..0b9a1552281 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -40,7 +40,7 @@ Migrating groups by direct transfer copies the groups from one place to another. - The subgroup of any existing top-level group. - Another GitLab instance, including GitLab.com. - In the [API](../../../api/bulk_imports.md), copy top-level groups and subgroups to these locations. -- Copy groups with projects (in [Beta](../../../policy/alpha-beta-support.md#beta) and not ready for production +- Copy groups with projects (in [Beta](../../../policy/experiment-beta-support.md#beta) and not ready for production use) or without projects. Copying projects with groups is available: - On GitLab.com by default. @@ -50,7 +50,7 @@ Not all group and project resources are copied. See list of copied resources bel - [Migrated project items](#migrated-project-items-beta). WARNING: -Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta). This feature is not +Importing groups with projects is in [Beta](../../../policy/experiment-beta-support.md#beta). This feature is not ready for production use. We invite you to leave your feedback about migrating by direct transfer in @@ -77,6 +77,13 @@ transfer. | 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: + +- [Group relations export API](../../../api/group_relations_export.md). +- [Project relations export API](../../../api/project_relations_export.md) + +If either API produces files larger than the maximum relation size limit, group migration by direct transfer fails. + ### Visibility rules After migration: @@ -86,7 +93,7 @@ After migration: - Stay public when copied into a public group. - Become private when copied into a private group. -If used a private network on your source instance to hide content from the general public, +If you used a private network on your source instance to hide content from the general public, make sure to have a similar setup on the destination instance, or to import into a private group. ### Prerequisites @@ -129,10 +136,10 @@ To ensure GitLab maps users and their contributions correctly: Create the group you want to import to and connect the source GitLab instance: 1. Create either: - - A new group. On the top bar, select **{plus-square}**, then **New group**, and select **Import group**. + - A new group. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. Then select **Import group**. - A new subgroup. On existing group's page, either: - Select **New subgroup**. - - On the top bar, Select **{plus-square}** and then **New subgroup**. Then on the left sidebar, select the **import an existing group** link. + - On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New subgroup**. Then select the **import an existing group** link. 1. Enter the URL of a GitLab instance running GitLab 14.0 or later. 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. @@ -153,7 +160,7 @@ role. 1. After a group has been imported, select its GitLab path to open its GitLab URL. WARNING: -Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta). This feature is not +Importing groups with projects is in [Beta](../../../policy/experiment-beta-support.md#beta). This feature is not ready for production use. ### Group import history @@ -169,8 +176,7 @@ You can view all groups migrated by you by direct transfer listed on the group i To view group import history: 1. Sign in to GitLab. -1. On the top bar, select **Create new…** (**{plus-square}**). -1. Select **New group**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. 1. Select **Import group**. 1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. @@ -220,6 +226,13 @@ Group items that are migrated to the destination GitLab instance include: - Already exists in the destination GitLab instance. - Has a public email in the source GitLab instance that matches a confirmed email in the destination GitLab instance. +#### Excluded items + +Some group items are excluded from migration because they either: + +- May contain sensitive information: CI/CD variables, webhooks, and deploy tokens. +- Are not supported: push rules. + ### Migrated project items (Beta) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. @@ -251,7 +264,7 @@ If you choose not to migrate projects along with groups or if you want to retry initiate project-only migrations using the [API](../../../api/bulk_imports.md). WARNING: -Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta) +Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/experiment-beta-support.md#beta) and is not ready for production use. Project items that are migrated to the destination GitLab instance include: @@ -325,9 +338,24 @@ Setting-related project items that are migrated to the destination GitLab instan #### Excluded items -Project items excluded from migration because they contain sensitive information: - -- Pipeline triggers. +Some project items are excluded from migration because they either: + +- May contain sensitive information: + - CI/CD variables + - Deploy keys + - Deploy tokens + - Pipeline schedule variables + - Pipeline triggers + - Webhooks +- Are not supported: + - Agents + - Container Registry + - Environments + - Feature flags + - Infrastructure Registry + - Package Registry + - Pages domains + - Remote mirrors ### Troubleshooting @@ -378,8 +406,8 @@ To solve this, you must change the source group path to include a non-numerical - The GitLab UI: - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. On the left sidebar, select **Settings > General**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. Select **Settings > General**. 1. Expand **Advanced**. 1. Under **Change group URL**, change the group URL to include non-numeric characters. @@ -493,7 +521,8 @@ Prerequisite: To enable import and export for a group: -1. On the top bar, select **Main menu > Admin**. +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 **Visibility and access controls**. 1. In the **Import sources** section, select the checkboxes for the sources you want. @@ -506,9 +535,9 @@ Prerequisites: To export the contents of a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. In the **Advanced** section, select **Export Group**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. In the **Advanced** section, select **Export group**. 1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in NDJSON format. 1. Alternatively, you can download the export from the UI: @@ -521,15 +550,13 @@ You can also export a group [using the API](../../../api/group_import_export.md) ### Import the group -1. Create a new group: - - On the top bar, select **Create new…** (**{plus-square}**) and then **New group**. - - On an existing group's page, select **New subgroup**. -1. Select **Import group**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New subgroup**. +1. Select the **import an existing group** link. 1. Enter your group name. 1. Accept or modify the associated group URL. -1. Select **Choose file**. +1. Select **Choose file...**. 1. Select the file that you exported in the [Export a group](#export-a-group) section. -1. To begin importing, select **Import group**. +1. To begin importing, select **Import**. Your newly imported group page appears after the operation completes. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 7e093ccb01b..322cefc71d9 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -21,10 +21,10 @@ For larger organizations, you can also create [subgroups](subgroups/index.md). For more information about creating and managing your groups, see [Manage groups](manage.md). NOTE: -Self-managed customers should create a top-level group so you can see an overview of -your organization. For more information about efforts to create an +For self-managed customers it could be beneficial to create one single top-level group, so you can see an overview of +your entire organization. For more information about efforts to create an organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitlab-org/-/epics/9266). -A top-level group can also have one complete +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 @@ -45,29 +45,242 @@ empty for anonymous users. The group page has a visibility level icon. Administrator users cannot create a subgroup or project with a higher visibility level than that of the immediate parent group. -## Related topics - -- [Group wikis](../project/wiki/index.md) -- [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). -- [Repositories analytics](repositories_analytics/index.md): View overall activity of all projects with code coverage. -- [Contribution analytics](contribution_analytics/index.md): View the contributions (pushes, merge requests, - and issues) of group members. -- [Issue analytics](issues_analytics/index.md): View a bar chart of your group's number of issues per month. -- Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. -- [Epics](epics/index.md): Track groups of issues that share a theme. -- [Security Dashboard](../application_security/security_dashboard/index.md): View the vulnerabilities of all - the projects in a group and its subgroups. -- [Insights](insights/index.md): Configure insights like triage hygiene, issues created/closed per a given period, and - average time for merge requests to be merged. -- [Webhooks](../project/integrations/webhooks.md). -- [Kubernetes cluster integration](clusters/index.md). -- [Audit Events](../../administration/audit_events.md#group-events). -- [CI/CD minutes quota](../../ci/pipelines/cicd_minutes.md): Keep track of the CI/CD minute quota for the group. -- [Integrations](../admin_area/settings/project_integration_management.md). -- [Transfer a project into a group](../project/settings/index.md#transfer-a-project-to-another-namespace). -- [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. -- [Lock the sharing with group feature](access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). -- [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA - for all group members. -- Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/index.md). -- [Control access and visibility](../admin_area/settings/visibility_and_access_controls.md). +## View groups + +To explore all public groups: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your groups**. +1. At the top right, select **Explore groups**. + +To view groups where you have a direct or indirect membership: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your groups**. + +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. + +## Create a group + +To create a group: + +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. +1. Select **Create group**. +1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see + [reserved names](../reserved_names.md). +1. Enter a path for the group in **Group URL**, which is used for the [namespace](../namespace/index.md). +1. Choose the [visibility level](../public_access.md). +1. Personalize your GitLab experience by answering the following questions: + - What is your role? + - Who is using this group? + - What are you using this group for? +1. Invite GitLab members or other users to join the group. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For details about groups, watch [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). + +## Remove a group + +> 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. + +To remove a group and its contents: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Advanced** section. +1. In the **Remove group** section, select **Remove group**. +1. Type the group name. +1. Select **Confirm**. + +A group can also be removed from the groups dashboard: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your groups**. +1. Select (**{ellipsis_v}**) for the group you want to delete. +1. Select **Delete**. +1. In the Remove group section, select **Remove group**. +1. Type the group name. +1. Select **Confirm**. + +This action removes the group. It also adds a background job to delete all projects in the group. + +In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](https://about.gitlab.com/pricing/ultimate/), this action adds a background job to mark a group for deletion. By default, the job schedules the deletion seven days in the future. You can modify this retention period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#deletion-protection). + +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)** + +> - [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. + +If you don't want to wait, you can remove a group immediately. + +Prerequisites: + +- You must have the Owner role for a group. +- You have [marked the group for deletion](#remove-a-group). + +To immediately remove a group marked for deletion: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the "Permanently remove group" section, select **Remove group**. +1. Confirm the action when asked to. + +Your group, its subgroups, projects, and all related resources, including issues and merge requests, +are deleted. + +## Restore a group **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. + +To restore a group that is marked for deletion: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand the **Advanced** section. +1. In the Restore group section, select **Restore group**. + +## Request access to a group + +As a user, you can request to be a member of a group, if an administrator allows it. + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your groups**. +1. At the top right side, select **Explore groups**. +1. Under the group name, select **Request Access**. + +As many as ten of the most-recently-active group owners receive an email with your request. +Any group owner can approve or decline the request. + +If you change your mind before your request is approved, select +**Withdraw Access Request**. + +## Filter and sort members in a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289911) in GitLab 13.8. + +To find members in a group, you can sort, filter, or search. + +### Filter a group + +Filter a group to find members. By default, all members in the group and subgroups are displayed. + +In lists of group members, entries can display the following badges: + +- **SAML**, to indicate the member has a [SAML account](saml_sso/index.md) connected to them. +- **Enterprise**, to indicate that the member is an [enterprise user](../enterprise_user/index.md). + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. +1. Above the list of members, in the **Filter members** box, enter filter criteria. + - To view members in the group only, select **Membership = Direct**. + - To view members of the group and its subgroups, select **Membership = Inherited**. + - To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**. + - [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/349887), to view GitLab users created by [SAML SSO](saml_sso/index.md) or [SCIM provisioning](saml_sso/scim_setup.md) select **Enterprise = true**. + +### Search a group + +You can search for members by name, username, or email. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. +1. Above the list of members, in the **Filter members** box, enter search criteria. +1. To the right of the **Filter members** box, select the magnifying glass (**{search}**). + +### Sort members in a group + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. +1. Above the list of members, in the upper-right corner, from the **Account** list, select + the criteria to filter by. +1. To switch the sort between ascending and descending, to the right of the **Account** list, select the + arrow (**{sort-lowest}** or **{sort-highest}**). + +## Add users to a group + +You can give a user access to all projects in a group. + +Prerequisite: + +- You must have the Owner role. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. +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. +1. Select **Invite**. + +Members that are not automatically added are displayed on the **Invited** tab. +Users can be on this tab because they: + +- Have not yet accepted the invitation. +- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- [Exceed the group user cap](manage.md#user-cap-for-groups). + +## Remove a member from the group + +Prerequisites: + +- You must have the Owner role. +- The member must have direct membership in the group. If + membership is inherited from a parent group, then the member can be removed + from the parent group only. + +To remove a member from a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. +1. Next to the member you want to remove, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Remove member**. +1. Optional. On the **Remove member** confirmation box: + - To remove direct user membership from subgroups and projects, select the **Also remove direct user membership from subgroups and projects** checkbox. + - To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox. +1. Select **Remove member**. + +## Ensure removed users cannot invite themselves back + +Malicious users with the Maintainer or Owner role could exploit a race condition that allows +them to invite themselves back to a group or project that a GitLab administrator has removed them from. + +To avoid this problem, GitLab administrators can [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). + +## Add projects to a group + +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). +- While you are creating a project, select a group from the dropdown list. + + ![Select group](img/select_group_dropdown_13_10.png) + +### Specify who can add projects to a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. + +By default, users with: + +- At least the Developer role can create projects under a group. This default can be changed. +- At least the Maintainer role can fork projects into a group. This default prevents users with the Developer role from forking projects that + contain protected branches and cannot be changed. + +To change the role that can create projects under a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Select the desired option in the **Roles allowed to create projects** dropdown list. +1. Select **Save changes**. + +To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 17aa6cb9655..ab967c8b12c 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -23,8 +23,8 @@ Prerequisites: To access your group's insights: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Insights**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Insights**. ## Interact with insights charts @@ -65,9 +65,9 @@ To configure group insights: 1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md#configure-project-insights) in a project that belongs to your group. -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Analytics** tab and find the **Insights** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Analytics** and find the **Insights** section. 1. Select the project that contains your `.gitlab/insights.yml` configuration file. 1. Select **Save changes**. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index dbade014ec2..cc43ca80801 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -15,8 +15,8 @@ prior. To access the chart: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Issue Analytics**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Analyze > Issue analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 9b246e6ad47..a4677182bb0 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -50,8 +50,8 @@ Prerequisites: To create an iteration cadence: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Iterations**. 1. Select **New iteration cadence**. 1. Enter the title and description of the iteration cadence. 1. To manually manage the iteration cadence, clear the **Enable automatic scheduling** checkbox and skip the next step. @@ -70,8 +70,8 @@ If you want to manually manage the created cadence, read [Manual Iteration Manag ### View the iterations list -1. On the top bar, select **Main menu > Groups** and find your group. -1. Select **Issues > Iterations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Iterations**. To view all the iterations in a cadence, ordered by descending date, select that iteration cadence. From there you can create a new iteration or select an iteration to get a more detailed view. @@ -91,8 +91,8 @@ Prerequisites: To edit an iteration cadence: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Iterations**. 1. Select **Edit iteration cadence**. When you use automatic scheduling and edit the **Automation start date** field, @@ -105,8 +105,8 @@ doesn't delete the eight existing upcoming iterations. #### Turn on and off automatic scheduling for an iteration cadence -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Iterations**. 1. Next to the cadence for which you want to turn on or off automatic scheduling, select the three-dot menu (**{ellipsis_v}**) **> Edit cadence**. 1. Select or clear the **Enable automatic scheduling** checkbox. @@ -157,8 +157,8 @@ Deleting an iteration cadence also deletes all iterations within that cadence. To delete an iteration cadence: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Iterations**. 1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. 1. Select **Delete cadence**. @@ -178,8 +178,8 @@ Prerequisites: To create an iteration: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations** and select an iteration cadence. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Plan > Iterations** and select an iteration cadence. 1. Select **New iteration**. 1. Enter the title, a description (optional), a start date, and a due date. 1. Select **Create iteration**. The iteration details page opens. @@ -277,8 +277,8 @@ and get a more accurate understanding of scope attributable to each label. To group issues by label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Iterations**. 1. In the **Group by** dropdown list, select **Label**. 1. Select the **Filter by label** dropdown list. 1. Select the labels you want to group by in the labels dropdown list. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 7c2c2eaa211..284fb8b3d7c 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -9,245 +9,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use groups to manage one or more related projects at the same time. NOTE: -Self-managed customers should create a top-level group so you can see an overview of -your organization. For more information about efforts to create an +For self-managed customers it could be beneficial to create one single top-level group, so you can see an overview of +your entire organization. For more information about efforts to create an organization view of all groups, [see epic 9266](https://gitlab.com/groups/gitlab-org/-/epics/9266). -A top-level group can also have one complete +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 [Value stream analytics](../group/value_stream_analytics/index.md). -## View groups - -To view groups, on the top bar, select **Main menu > Groups > View all groups**. - -The **Groups** page shows a list of groups, sorted by last updated date. - -- To explore all public groups, select **Explore groups**. -- To view groups where you have a direct or indirect membership, select **Your groups**. This tab 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. - -## Create a group - -To create a group: - -1. On the top bar, either: - - Select **Main menu > Groups > View all groups**, and on the right, select **New group**. - - To the left of the search box, select the plus sign and then **New group**. -1. Select **Create group**. -1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see - [reserved names](../reserved_names.md). -1. Enter a path for the group in **Group URL**, which is used for the [namespace](../namespace/index.md). -1. Choose the [visibility level](../public_access.md). -1. Personalize your GitLab experience by answering the following questions: - - What is your role? - - Who is using this group? - - What are you using this group for? -1. Invite GitLab members or other users to join the group. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For details about groups, watch [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). - -## Remove a group - -To remove a group and its contents: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Advanced** section. -1. In the **Remove group** section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. - -A group can also be removed from the groups dashboard: - -1. On the top bar, select **Main menu > Groups > View all groups**. -1. Select **Your Groups**. -1. Select (**{ellipsis_v}**) for the group you want to delete. -1. Select **Delete**. -1. In the Remove group section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. - -This action removes the group. It also adds a background job to delete all projects in the group. - -Specifically: - -- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab Premium or Ultimate tiers](https://about.gitlab.com/pricing/premium/), this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#deletion-protection). - -- 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)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2. - -If you don't want to wait, you can remove a group immediately. - -Prerequisites: - -- You must have the Owner role for a group. -- You have [marked the group for deletion](#remove-a-group). - -To immediately remove a group marked for deletion: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand **Advanced**. -1. In the "Permanently remove group" section, select **Remove group**. -1. Confirm the action when asked to. - -Your group, its subgroups, projects, and all related resources, including issues and merge requests, -are deleted. - -## Restore a group **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. - -To restore a group that is marked for deletion: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. Select **Settings > General**. -1. Expand the **Path, transfer, remove** section. -1. In the Restore group section, select **Restore group**. - -## Request access to a group - -As a user, you can request to be a member of a group, if an administrator allows it. - -1. On the top bar, select **Main menu > Groups** and find your group. -1. Under the group name, select **Request Access**. - -As many as ten of the most-recently-active group owners receive an email with your request. -Any group owner can approve or decline the request. - -If you change your mind before your request is approved, select -**Withdraw Access Request**. - -## Filter and sort members in a group - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289911) in GitLab 13.8. - -To find members in a group, you can sort, filter, or search. - -### Filter a group - -Filter a group to find members. By default, all members in the group and subgroups are displayed. - -In lists of group members, entries can display the following badges: - -- **SAML**, to indicate the member has a [SAML account](saml_sso/index.md) connected to them. -- **Enterprise**, to indicate that the member is an [enterprise user](../enterprise_user/index.md). - -1. On the top bar, select **Main menu > Groups** and find your group. -1. Above the list of members, in the **Filter members** box, enter filter criteria. - - To view members in the group only, select **Membership = Direct**. - - To view members of the group and its subgroups, select **Membership = Inherited**. - - To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**. - - [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/349887), to view GitLab users created by [SAML SSO](saml_sso/index.md) or [SCIM provisioning](saml_sso/scim_setup.md) select **Enterprise = true**. - -### Search a group - -You can search for members by name, username, or email. - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. -1. Above the list of members, in the **Filter members** box, enter search criteria. -1. To the right of the **Filter members** box, select the magnifying glass (**{search}**). - -### Sort members in a group - -You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in**. - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. -1. Above the list of members, in the upper-right corner, from the **Account** list, select - the criteria to filter by. -1. To switch the sort between ascending and descending, to the right of the **Account** list, select the - arrow (**{sort-lowest}** or **{sort-highest}**). - -## Add users to a group - -You can give a user access to all projects in a group. - -Prerequisite: - -- You must have the Owner role. - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. -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. -1. Select **Invite**. - -Members that are not automatically added are displayed on the **Invited** tab. -Users can be on this tab because they: - -- Have not yet accepted the invitation. -- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). -- [Exceed the group user cap](#user-cap-for-groups). - -## Remove a member from the group - -Prerequisites: - -- You must have the Owner role. -- The member must have direct membership in the group. If - membership is inherited from a parent group, then the member can be removed - from the parent group only. - -To remove a member from a group: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Members**. -1. Next to the member you want to remove, select **Remove member**. -1. Optional. On the **Remove member** confirmation box: - - To remove direct user membership from subgroups and projects, select the **Also remove direct user membership from subgroups and projects** checkbox. - - To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox. -1. Select **Remove member**. - -## Ensure removed users cannot invite themselves back - -Malicious users with the Maintainer or Owner role could exploit a race condition that allows -them to invite themselves back to a group or project that a GitLab administrator has removed them from. - -To avoid this problem, GitLab administrators can [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). - -## Add projects to a group - -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). -- While you are creating a project, select a group from the dropdown list. - - ![Select group](img/select_group_dropdown_13_10.png) - -### Specify who can add projects to a group - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. - -By default, users with at least the Developer role can create projects under a group. - -To change this setting for a specific group: - -1. On the top bar, select **Main menu > Groups > View all groups**. -1. Select **Your Groups**. -1. Find the group and select it. -1. From the left menu, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Roles allowed to create projects** dropdown list. -1. Select **Save changes**. - -To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - -## Add Group README +## Add a group README As a group owner or member, you can use a README to provide more information about your team, and invite users to contribute to your projects. The README is displayed on the group overview page, and can be changed in the group settings. All group members can edit the README. @@ -258,8 +29,8 @@ Prerequisite: To add a group README: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. In the **Group README** section, select **Add README**. This action creates a new project `gitlab-profile` that contains the `README.md` file. 1. On the prompt for creating a README, select **Create and add README**. You're redirected to the Web IDE, where a README file is created. 1. In the Web IDE, edit and commit the `README.md` file. @@ -270,13 +41,13 @@ You can change the owner of a group. Each group must always have at least one member with the Owner role. - As an administrator: - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. On the left sidebar, select **Group information > Members**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. Select **Manage > Members**. 1. Give a different member the **Owner** role. 1. Refresh the page. You can now remove the **Owner** role from the original owner. - As the current group's owner: - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. On the left sidebar, select **Group information > Members**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. Select **Manage > Members**. 1. Give a different member the **Owner** role. 1. Have the new owner sign in and remove the **Owner** role from you. @@ -301,8 +72,8 @@ create a new group and transfer projects to it instead. To change your group path (group URL): -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General** page. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Under **Change group URL**, enter a new name. 1. Select **Change group URL**. @@ -349,7 +120,7 @@ To share a given group, for example, `Frontend` with another group, for example, `Engineering`: 1. Go to the `Frontend` group. -1. On the left sidebar, select **Group information > Members**. +1. Select **Manage > Members**. 1. Select **Invite a group**. 1. In the **Select a group to invite** list, select `Engineering`. 1. Select a [role](../permissions.md) as maximum access level. @@ -360,6 +131,22 @@ After sharing the `Frontend` group with the `Engineering` group: - The **Groups** tab lists the `Engineering` group. - The **Groups** tab lists a group regardless of whether it is a public or private group. - All direct members of the `Engineering` group have access to the `Frontend` group. Direct members of `Engineering` that gain access to the `Frontend` group keep their same access level as in `Engineering`, but up to the maximum access level selected when sharing the group. Inherited members of the `Engineering` group do not gain access to the `Frontend` group. +- All direct members of the `Engineering` group count towards the billable members of the `Frontend` group. + +## Remove a shared group + +To unshare a group: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. +1. Select the **Groups** tab. +1. To the right of the account you want to remove, select **Remove group** (**{remove}**). + +For example, if the `Engineering` group is shared with the `Frontend` group, when +you unshare the `Engineering` group: + +- All direct members of the `Engineering` group no longer have access to the `Frontend` group. +- Members of the `Engineering` group no longer count towards the billable members of the `Frontend` group. ## Transfer a group @@ -387,55 +174,13 @@ When transferring groups, note: To transfer a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Transfer group**. 1. Select the group name in the drop down menu. 1. Select **Transfer group**. -## Enable delayed project deletion **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -> - [Inheritance and enforcement added](https://gitlab.com/gitlab-org/gitlab/-/issues/321724) in GitLab 13.11. -> - [Instance setting to enable by default added](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. -> - [Instance setting is inherited and enforced when disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -> - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. -> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default. -> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) on May 08, 2023. -> - Enabled delayed deletion by default and removed the option to delete immediately [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -[Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for -[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) are enabled for either groups only or groups and projects. -When enabled on groups, projects in the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. -The default period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#retention-period). - -On self-managed GitLab, projects are deleted immediately by default. -In GitLab 14.2 and later, an administrator can -[change the default setting](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) -for projects in newly-created groups. - -On GitLab.com, see the [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for -the default setting. - -To enable delayed deletion of projects in a group: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Scroll to: - - (GitLab 15.1 and later) **Deletion protection** and select **Keep deleted projects**. - - (GitLab 15.0 and earlier) **Enable delayed project deletion** and tick the checkbox. -1. Optional. To prevent subgroups from changing this setting, select: - - (GitLab 15.1 and later), **Enforce deletion protection for all subgroups** - - (GitLab 15.0 and earlier), **Enforce for all subgroups**. -1. Select **Save changes**. - -In GitLab 13.11 and later, the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md), inheritance can be overridden unless enforced by an ancestor. - -In GitLab 15.11 with the `always_perform_delayed_deletion` feature flag enabled, this setting is removed -and all projects are deleted after the [retention period defined by the admin](../admin_area/settings/visibility_and_access_controls.md#retention-period). This will be the default behavior in GitLab 16.0 and later. - ## Disable email notifications > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23585) in GitLab 12.2. @@ -444,8 +189,8 @@ You can disable all email notifications related to the group, which includes its To disable email notifications: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Email notifications are disabled**. 1. Select **Save changes**. @@ -464,8 +209,8 @@ This is particularly helpful for groups with a large number of users. To disable group mentions: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Group mentions are disabled**. 1. Select **Save changes**. @@ -477,8 +222,8 @@ To disable group mentions: You can export a list of members in a group or subgroup as a CSV. -1. On the top bar, select **Main menu > Groups** and find your group or subgroup. -1. On the left sidebar, select either **Group information > Members** or **Subgroup information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group or subgroup. +1. On the left sidebar, **Manage > Members**. 1. Select **Export as CSV**. 1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -508,9 +253,9 @@ Prerequisite: To specify a user cap: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. You can set a cap on the top-level group only. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. In the **User cap** box, enter the desired number of users. 1. Select **Save changes**. @@ -530,8 +275,8 @@ Prerequisite: To remove the user cap: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. In the **User cap** box, delete the value. 1. Select **Save changes**. @@ -551,7 +296,7 @@ Prerequisite: To approve members that are pending because they've exceeded the user cap: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. On the left sidebar, select **Settings > Usage Quotas**. 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. @@ -582,8 +327,8 @@ For more information, see [group-level project templates](custom_project_templat To enable group file templates: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Templates** section. 1. Choose a project to act as the template repository. 1. Select **Save changes**. @@ -615,8 +360,8 @@ Prerequisites: To enable this setting: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Merge requests**. 1. Under **Merge checks**, select **Pipelines must succeed**. This setting also prevents merge requests from being merged if there is no pipeline. @@ -634,8 +379,8 @@ Prerequisite: To change this behavior: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Merge requests**. 1. Under **Merge checks**: - Select **Pipelines must succeed**. @@ -653,8 +398,8 @@ Prerequisite: To enable this setting: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Merge requests**. 1. Under **Merge checks**, select **All threads must be resolved**. 1. Select **Save changes**. @@ -666,91 +411,94 @@ To enable this setting: > - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. Group approval settings manage [project merge request approval settings](../project/merge_requests/approvals/settings.md) -at the top-level group level. These settings [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) +for all projects in a top-level group. These settings [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) that belong to the group. To view the merge request approval settings for a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand the **Merge request approvals** section. 1. Select the settings you want. 1. Select **Save changes**. -Support for group-level settings for merge request approval rules is tracked in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). +Approval settings should not be confused with [approval rules](../project/merge_requests/approvals/rules.md). Support +for the ability to set merge request approval rules for groups is tracked in +[epic 4367](https://gitlab.com/groups/gitlab-org/-/epics/4367). -## Group Code Suggestions **(FREE SAAS)** +## Enable Code Suggestions **(FREE SAAS)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405126) in GitLab 15.11. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. WARNING: -This feature is in [Beta](../../policy/alpha-beta-support.md#beta). -Code Suggestions use generative AI to suggest code while you're developing. -Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. +This feature is in [Beta](../../policy/experiment-beta-support.md#beta). +Due to high demand, this feature may have unscheduled downtime and Code Suggestions in IDEs may be delayed. Code Suggestions may produce [low-quality or incomplete suggestions](../project/repository/code_suggestions.md#model-accuracy-and-quality). Beta users should read about the [known limitations](../project/repository/code_suggestions.md#known-limitations). We look forward to hearing your feedback. -This setting enables users in the group to access [Code Suggestions](../project/repository/code_suggestions.md). -This setting [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) -that belong to the group. +You can give all users in a group and its subgroups access to [Code Suggestions](../project/repository/code_suggestions.md). + +- This setting + [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) in the group. +- Each user can + [enable or disable Code Suggestions for themselves](../project/repository/code_suggestions.md#enable-code-suggestions-for-an-individual-user). To enable Code Suggestions for a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Find the **Code Suggestions** settings. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Permissions and group features**. +1. Under **Code Suggestions**, select the **Projects in this group can use Code Suggestions** checkbox. 1. Select **Save changes**. -## Group Experiment features setting **(ULTIMATE SAAS)** +## Enable Experiment features **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404856) in GitLab 16.0. -You can give all users in the group access to Experiment features. - WARNING: -[Experiment features](../../policy/alpha-beta-support.md#experiment) may produce unexpected results +[Experiment features](../../policy/experiment-beta-support.md#experiment) may produce unexpected results (for example, the results might be low-quality, incomplete, incoherent, offensive, or insensitive, and might include insecure code or failed pipelines). +You can give all users in a top-level group access to Experiment features. This setting [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) that belong to the group. -To enable Experiment features for a group: +To enable Experiment features for a top-level group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Find the **Experiment features** settings. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Permissions and group features**. +1. Under **Experiment features**, select the **Use Experiment features** checkbox. 1. Select **Save changes**. -## Group third-party AI features setting **(ULTIMATE SAAS)** +## Enable third-party AI features **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404856) in GitLab 16.0. WARNING: -These Artifical Intelligence (AI) features use [third-party services](../ai_features.md#data-usage) +These AI features use [third-party services](../ai_features.md#data-usage) and require transmission of data, including personal data. -You can give all users in the group access to third-party AI features. +All users in the group have third-party AI features enabled by default. This setting [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) that belong to the group. -To enable third-party AI features for a group: +To disable third-party AI features for a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Find the **Third-party Artificial Intelligence (AI) features** settings. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Permissions and group features**. +1. Under **Third-party AI services**, uncheck the **Use third-party AI services** checkbox. 1. Select **Save changes**. ## Group activity analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/alpha-beta-support.md#beta). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/experiment-beta-support.md#beta). For a group, you can view how many merge requests, issues, and members were created in the last 90 days. @@ -764,105 +512,8 @@ Changes to [group wikis](../project/wiki/group.md) do not appear in group activi You can view the most recent actions taken in a group, either in your browser or in an RSS feed: -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. -1. On the left sidebar, select **Group information > Activity**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Manage > Activity**. To view the activity feed in Atom format, select the **RSS** (**{rss}**) icon. - -## Troubleshooting - -### Validation errors on namespaces and groups - -[GitLab 14.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70365) performs -the following checks when creating or updating namespaces or groups: - -- Namespaces must not have parents. -- Group parents must be groups and not namespaces. - -In the unlikely event that you see these errors in your GitLab installation, -[contact Support](https://about.gitlab.com/support/) so that we can improve this validation. - -### Find groups using an SQL query - -To find and store an array of groups based on an SQL query in the [rails console](../../administration/operations/rails_console.md): - -```ruby -# Finds groups and subgroups that end with '%oup' -Group.find_by_sql("SELECT * FROM namespaces WHERE name LIKE '%oup'") -=> [#<Group id:3 @test-group>, #<Group id:4 @template-group/template-subgroup>] -``` - -### Transfer subgroup to another location using Rails console - -If transferring a group doesn't work through the UI or API, you may want to attempt the transfer in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session): - -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 -user = User.find_by_username('<username>') -group = Group.find_by_name("<group_name>") -## Set parent_group = nil to make the subgroup a top-level group -parent_group = Group.find_by(id: "<group_id>") -service = ::Groups::TransferService.new(group, user) -service.execute(parent_group) -``` - -### Find groups pending deletion using Rails console - -If you need to find all the groups that are pending deletion, you can use the following command in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session): - -```ruby -Group.all.each do |g| - if g.marked_for_deletion? - puts "Group ID: #{g.id}" - puts "Group name: #{g.name}" - puts "Group path: #{g.full_path}" - end -end -``` - -### Delete a group using Rails console - -At times, a group deletion may get stuck. If needed, in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), -you can attempt to delete a group using the following command: - -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 -GroupDestroyWorker.new.perform(group_id, user_id) -``` - -### Find a user's maximum permissions for a group or project - -Administrators can find a user's maximum permissions for a group or project. - -1. Start a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). -1. Run the following commands: - - ```ruby - user = User.find_by_username 'username' - project = Project.find_by_full_path 'group/project' - user.max_member_access_for_project project.id - ``` - - ```ruby - user = User.find_by_username 'username' - group = Group.find_by_full_path 'group' - user.max_member_access_for_group group.id - ``` - -### Unable to remove billable members with badge `Project Invite/Group Invite` - -```plaintext -Members who were invited via a group invitation cannot be removed. You can either remove the entire group, or ask an Owner of the invited group to remove the member. -``` - -This error typically occurs when the user you're trying to remove is part of an external group that has been [shared with one or more of your projects](../project/members/share_project_with_groups.md) or [groups](#share-a-group-with-another-group). To remove the user as a billable member, follow one of the options: - -- Remove the invited group membership from your project or group members page. -- Recommended. Remove the user directly from the invited group, if you have access to the group. - -The feature request to **Update billable_members endpoint to include invited group** is currently being worked on. For more information, see [issue 386583](https://gitlab.com/gitlab-org/gitlab/-/issues/386583) diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 4ec86893524..1dde36c5c70 100644 --- a/doc/user/group/moderate_users.md +++ b/doc/user/group/moderate_users.md @@ -26,7 +26,7 @@ Prerequisites: To unban a user: 1. Go to the top-level group. -1. On the left sidebar, select **Group information > Members**. +1. On the left sidebar, select **Manage > Members**. 1. Select the **Banned** tab. 1. For the account you want to unban, select **Unban**. @@ -43,6 +43,6 @@ Prerequisites: To manually ban a user: 1. Go to the top-level group. -1. On the left sidebar, select **Group information > Members**. +1. On the left sidebar, select **Manage > Members**. 1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**). 1. From the dropdown list, select **Ban member**. diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index d5c44f4e245..ee8ac50f021 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -17,6 +17,10 @@ Git abuse rate limiting is a feature to automatically ban users who download, cl Git abuse rate limiting does not apply to top-level group owners, [deploy tokens](../../../user/project/deploy_tokens/index.md), or [deploy keys](../../../user/project/deploy_keys/index.md). +How GitLab determines a user's rate limit is under development. +GitLab team members can view more information in this confidential epic: +`https://gitlab.com/groups/gitlab-org/modelops/anti-abuse/-/epics/14`. + ## Automatic ban notifications If the `limit_unique_project_downloads_per_namespace_user` feature flag is enabled, selected users receive an email when a user is about to be banned. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index c2a4d8175b3..e5ca41accfc 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -37,8 +37,8 @@ The **Analytics > Repositories** group page displays the average test coverage o To see the latest code coverage for each project in your group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Repositories**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Repository analytics**. 1. In the **Latest test coverage results** section, from the **Select projects** dropdown list, choose the projects you want to check. You can download code coverage data for specific projects using @@ -52,8 +52,8 @@ You can get a CSV of the code coverage data for all of the projects in your grou To get the report: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Repositories**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Repository analytics**. 1. Select **Download historic test coverage data (.csv)**. 1. Select the projects and date range you want to include in the report. 1. Select **Download test coverage data (.csv)**. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index 524a5d5a9bd..f2db36e80b1 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -58,7 +58,7 @@ Attribute mapping: NOTE: Using the **Group ID** source attribute requires users to enter the group ID or object ID when configuring SAML group links. If available, use the **sAMAccountName** source attribute for the friendly group name instead. -[Azure AD limits the number of groups that can be sent in a SAML response to 150](https://support.esri.com/en-us/knowledge-base/000022190'). If a user is a member of more than 150 groups, Azure does not include that user's group claim in the SAML response. +[Azure AD limits the number of groups that can be sent in a SAML response to 150](https://support.esri.com/en-us/knowledge-base/000022190). If a user is a member of more than 150 groups, Azure does not include that user's group claim in the SAML response. ## Google Workspace diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index ee59eeb98db..dd455944bf8 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -125,7 +125,8 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure SAML](../../../integration/saml.md) for your self-managed GitLab instance. -1. On the top bar, select **Main menu > Admin**. +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 the **Visibility and access controls** section. 1. Ensure the **Lock memberships to SAML synchronization** checkbox is selected. @@ -225,7 +226,7 @@ in the user's SAML assertion. 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). -Otherwise, you can work around this issue by changing the [group claims](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/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. +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. ![Manage Group Claims](img/Azure-manage-group-claims.png). diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index a54b3fea53e..5838b9821de 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -38,8 +38,8 @@ If you are having issues setting up your identity provider, see the To set up SSO with Azure as your identity provider: -1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Go to Azure and [follow the instructions for configuring SSO for an application](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso). The following GitLab settings correspond to the Azure fields. @@ -71,8 +71,8 @@ For more information, see an [example configuration page](example_saml_config.md To set up Google Workspace as your identity provider: -1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Follow the instructions for [setting up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). The following GitLab settings correspond to the Google Workspace fields. @@ -115,8 +115,8 @@ View a demo of [how to configure SAML with Google Workspaces and set up Group Sy To set up SSO with Okta as your identity provider: -1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. Follow the instructions for [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). @@ -152,8 +152,8 @@ OneLogin supports its own [GitLab (SaaS) application](https://onelogin.service-n To set up OneLogin as your identity provider: -1. In GitLab, on the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Note the information on this page. 1. If you use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), @@ -179,8 +179,8 @@ To set up OneLogin as your identity provider: To configure some identity providers, you need a GitLab metadata URL. To find this URL: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. @@ -208,7 +208,7 @@ To change identity providers: To migrate users to a new email domain, tell users to: -1. Add their new email as the primary email to their accounts and verify it. +1. [Add their new email](../../profile/index.md#change-your-primary-email) as the primary email to their accounts and verify it. 1. Optional. Remove their old email from the account. If the **NameID** is configured with the email address, [change the **NameID** for users](#manage-user-saml-identity). @@ -217,8 +217,8 @@ If the **NameID** is configured with the email address, [change the **NameID** f After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Complete the fields: - In the **Identity provider single sign-on URL** field, enter the SSO URL from your identity provider. - In the **Certificate fingerprint** field, enter the fingerprint for the SAML token signing certificate. @@ -432,7 +432,7 @@ group owner, and then you can unlink the account. For example, to unlink the `MyOrg` account: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Disconnect** next to the connected account. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 38a1c4125aa..e5d6c86a5ac 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -25,8 +25,8 @@ Prerequisites: To configure GitLab SAML SSO SCIM: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > SAML SSO**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > SAML SSO**. 1. Select **Generate a SCIM token**. 1. For configuration of your identity provider, save the: - Token from the **Your SCIM token** field. @@ -190,8 +190,7 @@ During provisioning: - Both primary and secondary emails are considered when checking whether a GitLab user account exists. - Duplicate usernames are handled by adding suffix `1` when creating the user. For example, if `test_user` already - exists, `test_user1` is used. If `test_user1` already exists, GitLab increments the suffix until an unused username - is found. + exists, `test_user1` is used. If `test_user1` already exists, GitLab increments the suffix to find an unused username. If no unused username is found after 4 tries, a random string is attached to the username. On subsequent visits, new and existing users can access groups either: diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 4a2bfd4c4b4..e264778062b 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -57,8 +57,8 @@ all projects that have visibility level set to [Internal](../../public_access.md To create a group access token: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Access Tokens**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the group. 1. Enter an expiry date for the token: - The token expires on that date at midnight UTC. @@ -119,8 +119,8 @@ or API. However, administrators can use a workaround: To revoke a group access token: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Access Tokens**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Access Tokens**. 1. Next to the group access token to revoke, select **Revoke**. ## Revoke a group access token using Rails console @@ -153,8 +153,8 @@ The scope determines the actions you can perform when you authenticate with a gr To enable or disable group access token creation for all subgroups in a top-level group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Users can create project access tokens and group access tokens in this group**. @@ -168,7 +168,7 @@ These bot users are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects), except they are added to groups instead of projects. Bot users for groups: -- Do not count as licensed seats. +- Is not a billable user, so it does not count toward the license limit. - Can have a maximum role of Owner for a group. For more information, see [Create a group access token](../../../api/group_access_tokens.md#create-a-group-access-token). - Have a username set to `group_{group_id}_bot_{random_string}`. For example, `group_123_bot_4ffca233d8298ea1`. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 63ffbf62981..81e972bf73b 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -56,7 +56,7 @@ the private subgroup. To view the subgroups of a group: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select the **Subgroups and projects** tab. 1. To view a nested subgroup, expand a subgroup in the hierarchy list. @@ -84,7 +84,7 @@ You cannot host a GitLab Pages subgroup website with a top-level domain name. Fo To create a subgroup: -1. On the top bar, select **Main menu > Groups** and find and select the parent group to add a subgroup to. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a parent group for the subgroup. 1. On the parent group's overview page, in the upper-right corner, select **New subgroup**. 1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. @@ -99,13 +99,14 @@ Prerequisite: To change who can create subgroups on a group: - As a user with the Owner role on the group: - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. On the left sidebar, select **Settings > General**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select a role from **Roles allowed to create subgroups**. 1. Select **Save changes**. - As an administrator: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Groups**. 1. In the group's row select **Edit**. 1. Select a role from **Allowed to create subgroups**. @@ -160,8 +161,8 @@ Group permissions for a member can be changed only by: To see if a member has inherited the permissions from a parent group: -1. On the top bar, select **Main menu > Groups** and find the group. -1. Select **Group information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. Members list for an example subgroup _Four_: @@ -184,7 +185,7 @@ In the screenshot above: - Administrator has the Owner role on group _Four_ and is a member of all subgroups. For that reason, as with User 3, the **Source** column indicates they are a direct member. -Members can be [filtered by inherited or direct membership](../manage.md#filter-a-group). +Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). ### Override ancestor group membership diff --git a/doc/user/group/troubleshooting.md b/doc/user/group/troubleshooting.md new file mode 100644 index 00000000000..6de90053c21 --- /dev/null +++ b/doc/user/group/troubleshooting.md @@ -0,0 +1,102 @@ +--- +stage: Data Stores +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 +--- + +# Troubleshooting groups + +## Validation errors on namespaces and groups + +[GitLab 14.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70365) performs +the following checks when creating or updating namespaces or groups: + +- Namespaces must not have parents. +- Group parents must be groups and not namespaces. + +In the unlikely event that you see these errors in your GitLab installation, +[contact Support](https://about.gitlab.com/support/) so that we can improve this validation. + +## Find groups using an SQL query + +To find and store an array of groups based on an SQL query in the [rails console](../../administration/operations/rails_console.md): + +```ruby +# Finds groups and subgroups that end with '%oup' +Group.find_by_sql("SELECT * FROM namespaces WHERE name LIKE '%oup'") +=> [#<Group id:3 @test-group>, #<Group id:4 @template-group/template-subgroup>] +``` + +## Transfer subgroup to another location using Rails console + +If transferring a group doesn't work through the UI or API, you may want to attempt the transfer in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session): + +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 +user = User.find_by_username('<username>') +group = Group.find_by_name("<group_name>") +## Set parent_group = nil to make the subgroup a top-level group +parent_group = Group.find_by(id: "<group_id>") +service = ::Groups::TransferService.new(group, user) +service.execute(parent_group) +``` + +## Find groups pending deletion using Rails console + +If you need to find all the groups that are pending deletion, you can use the following command in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +Group.all.each do |g| + if g.marked_for_deletion? + puts "Group ID: #{g.id}" + puts "Group name: #{g.name}" + puts "Group path: #{g.full_path}" + end +end +``` + +## Delete a group using Rails console + +At times, a group deletion may get stuck. If needed, in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), +you can attempt to delete a group using the following command: + +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 +GroupDestroyWorker.new.perform(group_id, user_id) +``` + +## Find a user's maximum permissions for a group or project + +Administrators can find a user's maximum permissions for a group or project. + +1. Start a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Run the following commands: + + ```ruby + user = User.find_by_username 'username' + project = Project.find_by_full_path 'group/project' + user.max_member_access_for_project project.id + ``` + + ```ruby + user = User.find_by_username 'username' + group = Group.find_by_full_path 'group' + user.max_member_access_for_group group.id + ``` + +## Unable to remove billable members with badge `Project Invite/Group Invite` + +```plaintext +Members who were invited via a group invitation cannot be removed. You can either remove the entire group, or ask an Owner of the invited group to remove the member. +``` + +This error typically occurs when the user you're trying to remove is part of an external group that has been [shared with one or more of your projects](../project/members/share_project_with_groups.md) or [groups](manage.md#share-a-group-with-another-group). To remove the user as a billable member, follow one of the options: + +- Remove the invited group membership from your project or group members page. +- Recommended. Remove the user directly from the invited group, if you have access to the group. + +The feature request to **Update billable_members endpoint to include invited group** is currently being worked on. For more information, see [issue 386583](https://gitlab.com/gitlab-org/gitlab/-/issues/386583) diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index bc48c1050fb..952552fc648 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -51,6 +51,9 @@ Value stream analytics offers different features at the project and group level |Date filter behavior|Filters items [finished within the date range](https://gitlab.com/groups/gitlab-org/-/epics/6046)|Filters items by creation date.|Filters items by creation date.| |Authorization|At least reporter|At least reporter|Can be public| +NOTE: +Feature parity of project-level with group-level value stream analytics is achieved by using the new record `ProjectNamespace`. For details about this consolidation initiative, see the [Organization documentation](../../../development/organization/index.md). + ## How value stream analytics works Value stream analytics calculates the duration of every stage of your software development process. @@ -206,10 +209,8 @@ Prerequisites: To view value stream analytics for your group or project: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +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. To view metrics for a particular stage, select a stage below the **Filter results** text box. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -298,10 +299,8 @@ Prerequisite: To view key lifecycle metrics: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Analyze > Value stream analytics**. Key metrics display below the **Filter results** text box. 1. Optional. Filter the results: 1. Select the **Filter results** text box. @@ -314,10 +313,8 @@ To view key lifecycle metrics: To view the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md) and [DORA metrics](../../analytics/dora_metrics.md): -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +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 **Key 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`). @@ -331,10 +328,8 @@ Value stream analytics shows the median time spent by issues or merge requests i To view the median time spent in each stage by a group: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +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. Optional. Filter the results: 1. Select the **Filter results** text box. 1. Select a parameter. @@ -357,8 +352,8 @@ group and time frame. To view tasks by type: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Analyze > Value stream analytics**. 1. Below the **Filter results** text box, select **Overview**. The **Tasks by type** chart displays below the **Total time** chart. 1. To switch between the task type, select the **Settings** (**{settings}**) dropdown list and select **Issues** or **Merge Requests**. @@ -374,10 +369,8 @@ To view tasks by type: When you create a value stream, you can use GitLab default stages and hide or re-order them. You can also create custom stages in addition to those provided in the default template. -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value Stream**. +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. Select **Create new Value Stream**. 1. Enter a name for the value stream. 1. Select **Create from default template**. @@ -400,10 +393,8 @@ If you have recently upgraded to GitLab Premium, it can take up to 30 minutes fo When you create a value stream, you can create and add custom stages that align with your own development workflows. -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value Stream**. +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. Select **Create value stream**. 1. For each stage: - Enter a name for the stage. @@ -436,10 +427,8 @@ The first value stream uses standard timestamp-based events for defining the sta After you create a value stream, you can customize it to suit your purposes. To edit a value stream: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value Stream**. +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. In the upper-right corner, select the dropdown list, then select a value stream. 1. Next to the value stream dropdown list, select **Edit**. 1. Optional: @@ -457,9 +446,7 @@ After you create a value stream, you can customize it to suit your purposes. To To delete a custom value stream: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. In the upper-right corner, select the dropdown list, then select the value stream you would like to delete. 1. Select **Delete (name of value stream)**. 1. To confirm, select **Delete**. @@ -474,10 +461,8 @@ To delete a custom value stream: The **Total time chart** shows the average number of days it takes for development cycles to complete. The chart shows data for the last 500 workflow items. -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. +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. Above the **Filter results** box, select a stage: - To view a summary of the cycle time for all stages, select **Overview**. - To view the cycle time for specific stage, select a stage. diff --git a/doc/user/img/explain_this_vulnerability.png b/doc/user/img/explain_this_vulnerability.png Binary files differindex 0880ad5f875..bb938241911 100644 --- a/doc/user/img/explain_this_vulnerability.png +++ b/doc/user/img/explain_this_vulnerability.png diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index b571a65b50a..01911f2b889 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -34,17 +34,18 @@ your cluster's level. **Project-level clusters:** -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Kubernetes clusters**. **Group-level clusters:** -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Kubernetes**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Operate > Kubernetes clusters**. **Instance-level clusters:** -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Kubernetes**. ## Security implications for clusters connected with certificates diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index 45445c0a0f5..7c8065b6143 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -35,7 +35,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. In GitLab, on the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**.. 1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 4516ea538a9..19bcce581e9 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -34,7 +34,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. In GitLab, on the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index c8d2fb674b2..25a0a7149e0 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -41,7 +41,8 @@ Start by [importing the example project by URL](../../../project/import/repo_by_ To import the project: -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. In GitLab, on the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. On the right of the page, select **New project**. 1. Select **Import project**. 1. Select **Repository by URL**. diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index d4fc345f494..12ad207e4f8 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -64,8 +64,8 @@ In each GitLab major release (for example, 15.0), the latest templates replace t To use a Terraform template: -1. On the top bar, select **Main menu > Projects** and find the project you want to integrate with Terraform. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project you want to integrate with Terraform. +1. Select **Code > Repository**. 1. Edit your `.gitlab-ci.yml` file, use the `include` attribute to fetch the Terraform template: ```yaml @@ -73,7 +73,7 @@ To use a Terraform template: # To fetch the latest template, use: - template: Terraform.latest.gitlab-ci.yml # To fetch the advanced latest template, use: - - template: Terraform/Base.latest.gitlab-ci.yml + - template: Terraform/Base.latest.gitlab-ci.yml # To fetch the stable template, use: - template: Terraform.gitlab-ci.yml # To fetch the advanced stable template, use: diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 1b0065fd165..455f2ce19e8 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -116,8 +116,8 @@ inconsistent. Instead, use a remote storage resource. [initialized for CI/CD](#initialize-a-terraform-state-as-a-backend-by-using-gitlab-cicd). 1. Copy a pre-populated Terraform `init` command: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Infrastructure > Terraform states**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Operate > Terraform states**. 1. Next to the environment you want to use, select **Actions** (**{ellipsis_v}**) and select **Copy Terraform init command**. @@ -294,8 +294,8 @@ To read the Terraform state in the target project, you need at least the Develop To view Terraform state files: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Infrastructure > Terraform states**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Terraform states**. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/4563) to track improvements to this UI. diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index dc5d402d04b..51a4499d716 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -21,8 +21,9 @@ projects. To view the instance level Kubernetes clusters: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Kubernetes**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/markdown.md b/doc/user/markdown.md index b8ed1c06324..401fe0bcb09 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -567,13 +567,12 @@ This example links to `<wiki_root>/miscellaneous.md`: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322174) in GitLab 15.10. -NOTE: -Use of the diagrams.net editor is not available on offline environments. - In wikis, you can use the [diagrams.net](https://www.diagrams.net/) editor to create diagrams. You can also edit diagrams created with the diagrams.net editor. The diagram editor is available in both the Markdown editor and the content editor. +For more information, see [Diagrams.net](../administration/integration/diagrams_net.md). + ##### Markdown editor To create a diagram in the Markdown editor: @@ -631,7 +630,7 @@ GitLab Flavored Markdown recognizes the following: |:----------------------------------------------------------------------------|:------------------------------|:----------------------------------------|:-------------------------------| | specific user | `@user_name` | | | | specific group | `@group_name` | | | -| entire team | `@all` | | | +| entire team | [`@all`](discussions/index.md#mentioning-all-members) | | | | project | `namespace/project>` | | | | issue | ``#123`` | `namespace/project#123` | `project#123` | | merge request | `!123` | `namespace/project!123` | `project!123` | diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 030f6eb82ef..2abaf9f8008 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default. -OKRs are an [Experiment](../policy/alpha-beta-support.md#experiment). +OKRs are an [Experiment](../policy/experiment-beta-support.md#experiment). For the OKR feature roadmap, see [epic 7864](https://gitlab.com/groups/gitlab-org/-/epics/7864). FLAG: @@ -60,8 +60,8 @@ Prerequisites: To create an objective: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Plan > Issues**. 1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. 1. Select **New objective** again. 1. Enter the objective title. @@ -77,8 +77,8 @@ Prerequisites: To view an objective: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = objective`. 1. Select the title of an objective from the list. @@ -91,8 +91,8 @@ Prerequisites: To view a key result: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = key_result`. 1. Select the title of a key result from the list. @@ -222,7 +222,8 @@ To set health status of an OKR: ## Promote a key result to an objective -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386877) in GitLab 16.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386877) in GitLab 16.0. +> - Quick action `/promote_to` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. Prerequisites: @@ -234,6 +235,41 @@ To promote a key result: 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**).. 1. Select **Promote to objective**. +Alternatively, use the `/promote_to objective` [quick action](../user/project/quick_actions.md). + +## Copy objective or key result reference + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1. + +To refer to an objective or key result elsewhere in GitLab, you can use its full URL or a short reference, which looks like +`namespace/project-name#123`, where `namespace` is either a group or a username. + +To copy the objective or key result reference to your clipboard: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your objective or key result to view it. +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. + +You can now paste the reference into another description or comment. + +Read more about objective or key result references in [GitLab-Flavored Markdown](markdown.md#gitlab-specific-references). + +## Copy objective or key result email address + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1. + +You can create a comment in an objective or key result by sending an email. +Sending an email to this address creates a comment that contains the email body. + +For more information about creating comments by sending an email and the necessary configuration, see +[Reply to a comment by sending email](discussions/index.md#reply-to-a-comment-by-sending-email). + +To copy the objective's or key result's email address: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy objective email address** or **Copy key result email address**. + ## Close an OKR When an OKR is achieved, you can close it. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index d013e2813f7..3239467ceb6 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -9,7 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -To access the dashboard, on the top bar, select **Main menu > Operations**. +To access the dashboard: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. +1. Select **Operations**. ## Adding a project to the dashboard 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 9adb9313f09..b645dc3a3e6 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -12,27 +12,30 @@ WARNING: Deleting container images is a destructive action and can't be undone. To restore a deleted container image, you must rebuild and re-upload it. +## Garbage collection + Deleting a container image on self-managed instances doesn't free up storage space, it only marks the image as eligible for deletion. To actually delete unreferenced container images and recover storage space, administrators must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). On GitLab.com, the latest version of the Container Registry includes an automatic online garbage collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). -The automatic online garbage collector is an instance-wide feature, rolling out gradually to a subset -of the user base. Some new container image repositories created from GitLab 14.5 onward are served by this -new version of the Container Registry. In this new version of the Container Registry, layers that aren't -referenced by any image manifest, and image manifests that have no tags and aren't referenced by another -manifest (such as multi-architecture images), are automatically scheduled for deletion after 24 hours if -left unreferenced. +In this new version of the Container Registry, the following are automatically scheduled +for deletion in 24 hours if left unreferenced: + +- Layers that aren't referenced by any image manifest. +- Image manifests that have no tags and aren't referenced by another manifest (like multi-architecture images). + +The online garbage collector is an instance-wide feature, and applies to all namespaces. ## Use the GitLab UI To delete container images using the GitLab UI: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Packages and registries > Container Registry**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. For: + - A group, select **Operate > Container Registry**. + - A project, select **Deploy > Container Registry**. 1. From the **Container Registry** page, you can select what you want to delete, by either: diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index c27265ccc3f..f9b1138ed84 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -21,10 +21,10 @@ rate limits and speed up your pipelines. For more information about the Docker R You can view the Container Registry for a project or group. -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Packages and registries > Container Registry**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. For: + - A group, select **Operate > Container Registry**. + - A project, select **Deploy > Container Registry**. You can search, sort, filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) your container images. You can share a filtered view by copying the URL from your browser. @@ -38,10 +38,10 @@ If a project is public, the Container Registry is also public. You can use the Container Registry **Tag Details** page to view a list of tags associated with a given container image: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Packages and registries > Container Registry**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. For: + - A group, select **Operate > Container Registry**. + - A project, select **Deploy > Container Registry**. 1. Select your container image. You can view details about each tag, such as when it was published, how much storage it consumes, @@ -54,10 +54,10 @@ tags on this page. You can share a filtered view by copying the URL from your br To download and run a container image hosted in the Container Registry: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. -1. On the left sidebar, select **Packages and registries > Container Registry**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. For: + - A group, select **Operate > Container Registry**. + - A project, select **Deploy > Container Registry**. 1. Find the container image you want to work with and select **Copy**. ![Container Registry image URL](img/container_registry_hover_path_13_4.png) @@ -115,13 +115,13 @@ The Container Registry is enabled by default. You can, however, remove the Container Registry for a project: -1. On the top bar, select **Main menu > Projects**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable **Container Registry**. 1. Select **Save changes**. -The **Packages and registries > Container Registry** entry is removed from the project's sidebar. +The **Deploy > Container Registry** entry is removed from the project's sidebar. ## Change visibility of the Container Registry @@ -133,8 +133,8 @@ You can, however, change the visibility of the Container Registry for a project. For more information about the permissions that this setting grants to users, see [Container Registry visibility permissions](#container-registry-visibility-permissions). -1. On the top bar, select **Main menu > Projects**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand the section **Visibility, project features, permissions**. 1. Under **Container Registry**, select an option from the dropdown list: diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index f873453e049..e3ca78becf1 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -18,30 +18,10 @@ to automatically manage your container registry usage. ## Check Container Registry storage use The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. -This page includes the Container Registry usage, which is only available on GitLab.com. +This page includes the [Container Registry usage](../../usage_quotas.md#container-registry-usage), which is only available on GitLab.com. Measuring usage is only possible on the new version of the GitLab Container Registry backed by a -metadata database. Support for improvements is proposed in epic [5523](https://gitlab.com/groups/gitlab-org/-/epics/5523). -On self-managed instances, you cannot use the Container Registry with a metadata database. For the plan to change this behavior, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). - -Image layers stored in the Container Registry are deduplicated at the root namespace level. - -An image is only counted once if: - -- You tag the same image more than once in the same repository. -- You tag the same image across distinct repositories under the same root namespace. - -An image layer is only counted once if: - -- You share the image layer across multiple images in the same container repository, project, or group. -- You share the image layer across different repositories. - -Only layers that are referenced by tagged images are accounted for. Untagged images and any layers -referenced exclusively by them are subject to [online garbage collection](delete_container_registry_images.md). -Untagged images are automatically deleted after 24 hours if they remain unreferenced during that period. - -Image layers are stored on the storage backend in the original (usually compressed) format. This -means that the measured size for any given image layer should match the size displayed on the -corresponding [image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md#example-image-manifest). +metadata database, which is [available on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5523) since GitLab 15.7. +For information on the planned availability for self-managed instances, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). ## Cleanup policy @@ -249,8 +229,10 @@ For self-managed instances, those settings can be updated in the [Rails console] They are also available in the [administrator area](../../admin_area/index.md): -1. On the top bar, select **Main menu > Admin**. -1. Go to **Settings > CI/CD > Container Registry**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > CI/CD** +1. Expand **Container Registry**. ### Use the cleanup policy API diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index 68fe430e531..729f4919188 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -91,8 +91,8 @@ The following procedure uses these sample project names: There may be a delay while the images are queued and deleted. 1. Change the path or transfer the project: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > General**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Change path** text box, edit the path. 1. Select **Change path**. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index d7cf33cc2a4..ebe87332948 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -35,10 +35,12 @@ For a list of planned additions, view the ## Enable or turn off the Dependency Proxy for a group +> Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0. + To enable or turn off the Dependency Proxy for a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Packages and registries**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Packages and registries**. 1. Expand the **Dependency Proxy** section. 1. To enable the proxy, turn on **Enable Proxy**. To turn it off, turn the toggle off. @@ -50,8 +52,8 @@ for the entire GitLab instance. To view the Dependency Proxy: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Packages and registries > Dependency Proxy**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Operate > Dependency Proxy**. The Dependency Proxy is not available for projects. @@ -175,8 +177,8 @@ You can also use [custom CI/CD variables](../../../ci/variables/index.md#for-a-p To store a Docker image in Dependency Proxy storage: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Packages and registries > Dependency Proxy**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Operate > Dependency Proxy**. 1. Copy the **Dependency Proxy image prefix**. 1. Use one of these commands. In these examples, the image is `alpine:latest`. 1. You can also pull images by digest to specify exactly which version of an image to pull. @@ -360,3 +362,19 @@ a minimum of the Guest role in the Dependency Proxy group: For more information about the work to improve the error messages in similar cases to `Access denied`, see [issue 354826](https://gitlab.com/gitlab-org/gitlab/-/issues/354826). + +### `exec format error` when running images from the dependency proxy + +This error occurs if you try to use the dependency proxy on an ARM-based Docker install. +The dependency proxy only supports the x86_64 architecture when pulling an image with a specific tag. + +As a workaround, you can specify the SHA256 of the image to force the dependency proxy +to pull a different architecture: + +```shell +docker pull ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/library/docker:20.10.3@sha256:bc9dcf5c8e5908845acc6d34ab8824bca496d6d47d1b08af3baf4b3adb1bd8fe +``` + +In this example, `bc9dcf5c8e5908845acc6d34ab8824bca496d6d47d1b08af3baf4b3adb1bd8fe` is the SHA256 of the ARM based image. + +For more information about the work to add support for other architectures, see [issue 325669](https://gitlab.com/gitlab-org/gitlab/-/issues/325669). diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md index 3aaaf0c0186..4c625499d07 100644 --- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -26,7 +26,7 @@ image or tag from Docker Hub. ## Cleanup policies -> [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0. +> Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0. ### Enable cleanup policies from within GitLab diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index bad099e6733..d24808674dc 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -118,7 +118,7 @@ API or the UI. #### Do not allow duplicate Generic packages > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293755) in GitLab 13.12. -> - [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0. +> - Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0. To prevent users from publishing duplicate generic packages, you can use the [GraphQL API](../../../api/graphql/reference/index.md#packagesettings) or the UI. @@ -225,12 +225,12 @@ If you are receiving `HTTP 500: Internal Server Error` responses when publishing # Consolidated Object Storage settings gitlab_rails['object_store']['connection'] = { # Other connection settings - `aws_signature_version` => '4' + 'aws_signature_version' => '4' } # OR # Storage-specific form settings gitlab_rails['packages_object_store_connection'] = { # Other connection settings - `aws_signature_version` => '4' + 'aws_signature_version' => '4' } ``` diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index 6cea541a55d..2bff6f79a27 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -12,9 +12,8 @@ You can integrate the [Harbor container registry](../../../user/project/integrat You can view the Harbor Registry for a project or group. -1. On the top bar, select **Main menu > Projects/Groups**. -1. Go to the project or group that you are interested in. -1. On the left sidebar, select **Packages and registries > Harbor Registry**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Operate > Harbor Registry**. You can search, sort, and filter images on this page. You can share a filtered view by copying the URL from your browser. @@ -30,7 +29,8 @@ Default settings for the Harbor integration at the project level are inherited f To download and run a Harbor image hosted in the GitLab Harbor Registry: 1. Copy the link to your container image: - 1. Go to your project or group's **Packages and registries > Harbor Registry** and find the image you want. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. Select **Operate > Harbor Registry** and find the image you want. 1. Select the **Copy** icon next to the image name. 1. Use the command to run the container image you want. @@ -39,8 +39,8 @@ To download and run a Harbor image hosted in the GitLab Harbor Registry: To view the list of tags associated with a specific artifact: -1. Go to your project or group. -1. Go to **Packages and registries > Harbor Registry**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Go to **Operate > Harbor Registry**. 1. Select the image name to view its artifacts. 1. Select the artifact you want. @@ -55,13 +55,18 @@ To build and push to the Harbor Registry: 1. Authenticate with the Harbor Registry. 1. Run the command to build or push. -To view these commands, go to your project's **Packages and registries > Harbor Registry > CLI Commands**. +To view these commands: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Operate > Harbor Registry**. +1. Select **CLI Commands**. ## Disable the Harbor Registry for a project To remove the Harbor Registry for a project: -1. Go to your project/group's **Settings > Integrations** page. +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. Select **Save changes**. diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md deleted file mode 100644 index 8c1e8a2ad8a..00000000000 --- a/doc/user/packages/infrastructure_registry/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../terraform_module_registry/index.md' -remove_date: '2023-06-13' ---- - -This document was moved to [another location](../terraform_module_registry/index.md). - -<!-- This redirect file can be deleted after <2023-06-13>. --> -<!-- 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/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index fd8049d9b75..bcc55af65bc 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -474,6 +474,8 @@ To delete older package versions, consider using the Packages API or the UI. ### Do not allow duplicate Maven packages +> Required role [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) from Developer to Maintainer in GitLab 15.0. + To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. In the UI: diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 52fdda0d523..0fe2b39a591 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -119,15 +119,16 @@ Your package should now publish to the Package Registry when the pipeline runs. If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. -You can install a package from a GitLab project or instance: +You can install a package from a GitLab project, group, or instance: - **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 in the same GitLab group. - **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. ### Authenticate to the Package Registry -You must authenticate to the Package Registry to install a package from a private project. -No authentication is needed if the project is public. +You must authenticate to the Package Registry to install a package from a private project or a private group. +No authentication is needed if the project or the group is public. To authenticate with `npm`: @@ -145,7 +146,13 @@ If you're installing: npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token ``` - From the project level: +- From the group level: + + ```shell + npm config set -- //your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken=your_token + ``` + +- From the project level: ```shell npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token @@ -154,6 +161,7 @@ If you're installing: In these examples: - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. +- Replace `your_group_id` with your group ID, found on the group's home page. - Replace `your_project_id` is your project ID, found on the project's home page. - Replace `your_token` with a deploy token, group access token, project access token, or personal access token. @@ -185,6 +193,29 @@ To install a package from the instance level, the package must have been publish npm install @scope/my-package ``` +### Install from the group level + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed. + +1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). + +1. Set the registry + + ```shell + npm config set @scope:registry=https://your_domain_name/api/v4/groups/your_group_id/-/packages/npm/ + ``` + + - Replace `@scope` with the [root level group](#naming-convention) of the group you're installing to the package from. + - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. + - Replace `your_group_id` is your group ID, found on the group's home page. + +1. Install the package + + ```shell + npm install @scope/my-package + ``` + ### Install from the project level 1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index c97ce9ec593..ea9bfd7defb 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -316,6 +316,8 @@ nuget push <package_file> -Source <source_name> ### Publish a package with the .NET CLI +> Publishing a package with `--api-key` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) in GitLab 16.1. + Prerequisites: - [A NuGet package created with .NET CLI](https://learn.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). @@ -336,6 +338,21 @@ For example: dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab ``` +You can publish a package using the `--api-key` option instead of `username` and `password`: + +```shell +dotnet nuget push <package_file> --source <source_url> --api-key <gitlab_personal_access_token, deploy_token or job token> +``` + +- `<package_file>` is your package filename, ending in `.nupkg`. +- `<source_url>` is the URL of the NuGet Package Registry. + +For example: + +```shell +dotnet nuget push MyPackage.1.0.0.nupkg --source https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json --api-key <gitlab_personal_access_token, deploy_token or job token> +``` + ### Publish a NuGet package by using CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md index cd2b288094b..94e5af7cc04 100644 --- a/doc/user/packages/package_registry/supported_package_managers.md +++ b/doc/user/packages/package_registry/supported_package_managers.md @@ -25,6 +25,6 @@ The Package Registry supports the following package manager types: | [Go](../go_proxy/index.md) | 13.1+ | [Experiment](https://gitlab.com/groups/gitlab-org/-/epics/3043) | | [Ruby gems](../rubygems_registry/index.md) | 13.10+ | [Experiment](https://gitlab.com/groups/gitlab-org/-/epics/3200) | -[View what each status means](../../../policy/alpha-beta-support.md). +[View what each status means](../../../policy/experiment-beta-support.md). You can also use the [API](../../../api/packages.md) to administer the Package Registry. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 371ab83a4fb..7bff6cf8234 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -32,13 +32,19 @@ of each package management system to publish different package types to the same ## Store different package types in one GitLab project -Let's take a look at how you might create a public place to hold all of your public packages. +Let's take a look at how you might create one project to host all of your packages: 1. Create a new project in GitLab. The project doesn't require any code or content. 1. On the left sidebar, select **Project information**, and note the project ID. -1. Create an access token. All package types in the Package Registry are accessible by using - [GitLab personal access tokens](../../profile/personal_access_tokens.md). - If you're using CI/CD, you can use CI job tokens (`CI_JOB_TOKEN`) to authenticate. +1. Create an access token for authentication. All package types in the Package Registry can be published by using: + + - A [personal access token](../../profile/personal_access_tokens.md). + - A [CI/CD job token](../../../ci/jobs/ci_job_token.md) (`CI_JOB_TOKEN`) in a CI/CD job. + Any projects publishing packages to this project's registry should be listed + in this project's [job token allowlist](../../../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token). + + If the project is private, downloading packages requires authentication as well. + 1. Configure your local project and publish the package. You can upload all types of packages to the same project, or diff --git a/doc/user/packages/yarn_repository/index.md b/doc/user/packages/yarn_repository/index.md index c8f4985a518..262e15fe240 100644 --- a/doc/user/packages/yarn_repository/index.md +++ b/doc/user/packages/yarn_repository/index.md @@ -80,11 +80,9 @@ Third party images such as `node:latest` or `node:current` do not have direct ac to the `CI_JOB_TOKEN` when operating in a shared runner. You must configure an authentication token or use a private runner. -To create a authentication token: +To create an authentication token for your project or group: -1. On the top bar, select **Main menu**, and: - - For a project, select **Projects** and find your project. - - For a group, select **Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. On the left sidebar, select **Settings > Repository > Deploy Tokens**. 1. Create a deployment token with `read_package_registry` and `write_package_registry` scopes and copy the generated token. 1. On the left sidebar, select **Settings > CI/CD > Variables**. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 418c01cd851..0b02de59ab4 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -129,7 +129,7 @@ The following table lists project permissions available for each role: | [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](discussions/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](project/merge_requests/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | | [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (6) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -369,6 +369,7 @@ The following table lists group permissions available for each role: | View [Productivity analytics](analytics/productivity_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | Create and edit [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | | Create project in group | | | ✓ (2)(4) | ✓ (2) | ✓ (2) | +| Fork project into a group | | | | ✓ | ✓ | | Create/edit/delete group milestones | | ✓ | ✓ | ✓ | ✓ | | Create/edit/delete iterations | | ✓ | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | @@ -400,14 +401,14 @@ The following table lists group permissions available for each role: | View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (3) | | Manage group runners | | | | | ✓ | | [Migrate groups](group/import/index.md) | | | | | ✓ | -| Manage [subscriptions, and purchase CI/CD minutes and storage](../subscriptions/gitlab_com/index.md) | | | | | ✓ | +| Manage [subscriptions, and purchase storage and units of compute](../subscriptions/gitlab_com/index.md) | | | | | ✓ | <!-- markdownlint-disable MD029 --> 1. Groups can be set to allow either Owners, or Owners and users with the Maintainer role, to [create subgroups](group/subgroups/index.md#create-a-subgroup). 2. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - - The [group level](group/manage.md#specify-who-can-add-projects-to-a-group). + - The [group level](group/index.md#specify-who-can-add-projects-to-a-group). 3. Does not apply to subgroups. 4. Developers can push commits to the default branch of a new project only if the [default branch protection](group/manage.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". 5. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. @@ -463,12 +464,14 @@ To work around the issue, give these users the Guest role or higher to any proje - [Confidential issues](project/issues/confidential_issues.md) - [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) - [Release permissions](project/releases/index.md#release-permissions) +- [Read-only namespaces](../user/read_only_namespaces.md) ## Custom roles **(ULTIMATE)** > - [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. Custom roles allow group members who are assigned the Owner role to create roles specific to the needs of their organization. @@ -476,6 +479,13 @@ specific to the needs of their organization. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code on private repositories via custom role](https://www.youtube.com/watch?v=46cp_-Rtxps). +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. + +You can discuss individual custom role and permission requests in [issue 391760](https://gitlab.com/gitlab-org/gitlab/-/issues/391760). + ### Create a custom role To enable custom roles for your group, a group member with the Owner role: @@ -483,7 +493,21 @@ To enable custom roles for your group, a group member with the Owner role: 1. Makes sure that there is at least one private project in this group or one of its subgroups, so that you can see the effect of giving a Guest a custom role. 1. Creates a personal access token with the API scope. -1. Uses [the API](../api/member_roles.md#add-a-member-role-to-a-group) to create the Guest+1 role for the root group. +1. Uses [the API](../api/member_roles.md#add-a-member-role-to-a-group) to create a custom role for the root group. + +#### Custom role requirements + +For every ability, a minimal access level is defined. To be able to create a custom role which enables a certain ability, the `member_roles` table record has to have the associated minimal access level. For all abilities, the minimal access level is Guest. Only users who have at least the Guest role can be assigned to a custom role. + +Some roles and abilities require having other abilities enabled. For example, a custom role can only have administration of vulnerabilities (`admin_vulnerability`) enabled if reading vulnerabilities (`read_vulnerability`) is also enabled. + +You can see the required minimal access levels and abilities requirements in the following table. + +| Ability | Minimal access level | Required ability | +| -- | -- | -- | +| `read_code` | Guest | - | +| `read_vulnerability` | Guest | - | +| `admin_vulnerability` | Guest | `read_vulnerability` | ### Associate a custom role with an existing group member diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index b5f936e7848..0d97c008561 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -6,16 +6,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Product analytics (Experiment) **(ULTIMATE)** -> - Introduced in GitLab 15.4 as an [Experiment](../../policy/alpha-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - Introduced in GitLab 15.4 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. > - `cube_api_proxy` revised to only reference the [Product Analytics API](../../api/product_analytics.md) in GitLab 15.6. > - `cube_api_proxy` removed and replaced with `product_analytics_internal_preview` in GitLab 15.10. > - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. +> - Snowplow integration introduced in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. On GitLab.com, this feature is not available. This feature is not ready for production use. +FLAG: +On self-managed GitLab, by default the Snowplow integration is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + This page is a work in progress, and we're updating the information as we add more features. For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). @@ -23,9 +29,9 @@ For more information, see the [group direction page](https://about.gitlab.com/di Product analytics uses several tools: -- [**Jitsu**](https://jitsu.com/docs) - A web and app event collection platform that provides a consistent API to collect user data and pass it through to ClickHouse. +- [**Snowplow**](https://docs.snowplow.io/docs) - A developer-first engine for collecting behavioral data, and passing it through to ClickHouse. - [**ClickHouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. -- [**Cube.js**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in Clickhouse. +- [**Cube**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in Clickhouse. The following diagram illustrates the product analytics flow: @@ -34,19 +40,21 @@ The following diagram illustrates the product analytics flow: title: Product Analytics flow --- flowchart TB - subgraph Adding data - A([SDK]) --Send user data--> B[Analytics Proxy] - B --Transform data and pass it through--> C[Snowplow] - C --Pass the data to the associated database--> D([Clickhouse]) + subgraph Event collection + A([SDK]) --Send user data--> B[Snowplow Collector] + B --Pass data through--> C[Snowplow Enricher] + end + subgraph Data warehouse + C --Transform and enrich data--> D([Clickhouse]) end - subgraph Showing dashboards - E([Dashboards]) --Generated from the YAML definition--> F[Dashboard] + subgraph Data visualization with dashboards + E([Dashboards]) --Generated from the YAML definition--> F[Panels/Visualizations] F --Request data--> G[Product Analytics API] - G --Run Cube queries with pre-aggregations--> H[Cube.js] + G --Run Cube queries with pre-aggregations--> H[Cube] H --Get data from database--> D D --Return results--> H - H --> G - G --Transform data to be rendered--> F + H --Transform data to be rendered--> G + G --Return data--> F end ``` @@ -69,113 +77,53 @@ Prerequisite: - You must be an administrator of a self-managed GitLab instance. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Analytics** tab and find the **Product analytics** section. 1. Select **Enable product analytics** and enter the configuration values. - The following table shows the required configuration parameters and example values: - - | Name | Value | - |--------------------------------|------------------------------------------------------------| - | Configurator connection string | `https://test:test@configurator.gitlab.com` | - | Jitsu host | `https://jitsu.gitlab.com` | - | Jitsu project ID | `g0maofw84gx5sjxgse2k` | - | Jitsu administrator email | `jitsu.admin@gitlab.com` | - | Jitsu administrator password | `<your_password>` | - | Collector host | `https://collector.gitlab.com` | - | ClickHouse URL | `https://<username>:<password>@clickhouse.gitlab.com:8123` | - | Cube API URL | `https://cube.gitlab.com` | - | Cube API key | `25718201b3e9...ae6bbdc62dbb` | - 1. Select **Save changes**. -## Product analytics dashboards +### Project-level settings -> - Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default. -> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. +You can override the instance-level settings defined by the administrator on a per-project basis. This allows you to +have a different configured product analytics instance for your project. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - -Each project can have an unlimited number of dashboards. -These dashboards are defined using the GitLab YAML schema, and stored in the `.gitlab/analytics/dashboards/` directory of a project repository. -The name of the file is the name of the dashboard. -Each dashboard can contain one or more visualizations (charts), which are shared across dashboards. - -Project maintainers can enforce approval rules on dashboard changes using features such as code owners and approval rules. -Dashboards are versioned in source control with the rest of a project's code. +Prerequisites: -### View project dashboards +- 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. -> Introduced in GitLab 15.9 behind the [feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. 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, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - -To view a list of product analytics dashboards for a project: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Dashboards**. -1. From the list of available dashboards, select the dashboard you want to view. - -### Define a dashboard - -To define a dashboard: - -1. In `.gitlab/analytics/dashboards/`, create a directory named like the dashboard. - - Each dashboard should have its own directory. -1. In the new directory, create a `.yaml` file with the same name as the directory. - - This file contains the dashboard definition. It must conform to the JSON schema defined in `ee/app/validators/json_schemas/product_analytics_dashboard.json`. -1. In the `.gitlab/analytics/dashboards/visualizations/` directory, create a `.yaml` file. - - This file defines the visualization type for the dashboard. It must conform to the schema in - `ee/app/validators/json_schemas/product_analytics_visualization.json`. - -For example, if you want to create three dashboards (Conversion funnels, Demographic breakdown, and North star metrics) -and one visualization (line chart) that applies to all dashboards, the file structure would be: +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. Select **Save changes**. -```plaintext -.gitlab/analytics/dashboards -├── conversion_funnels -│ └── conversion_funnels.yaml -├── demographic_breakdown -│ └── demographic_breakdown.yaml -├── north_star_metrics -| └── north_star_metrics.yaml -├── visualizations -│ └── example_line_chart.yaml -``` +## Instrument a GitLab project -### Define a chart visualization +To instrument code to collect data, use one or more of the existing SDKs: -You can define different charts, and add visualization options to some of them: +- [Browser SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-browser) +- [Ruby SDK](https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-rb) -- Line chart, with the options listed in the [ECharts documentation](https://echarts.apache.org/en/option.html). -- Column chart, with the options listed in the [ECharts documentation](https://echarts.apache.org/en/option.html). -- Data table, with the only option to render `links` (array of objects, each with `text` and `href` properties to specify the dimensions to be used in links). See [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/analytics_visualization.json?ref_type=heads#L112)). -- Single stat, with the only option to set `decimalPlaces` (number, default value is 0). +## Product analytics dashboards -To define a chart for your dashboards: +> - Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default. +> - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. -1. In the `.gitlab/product_analytics/dashboards/visualizations/` directory, create a `.yaml` file. -The filename should be descriptive of the visualization it defines. -1. In the `.yaml` file, define the visualization options, according to the schema in -`ee/app/validators/json_schemas/analytics_visualization.json`. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. -For [example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/assets/javascripts/analytics/analytics_dashboards/gl_dashboards/product_analytics/visualizations/events_over_time.json), to create a line chart that illustrates event count over time, in the `visualizations` folder -create a `line_chart.yaml` file with the following required fields: +Product analytics dashboards are a subset of dashboards under [Analytics dashboards](../analytics/analytics_dashboards.md). -- version -- title -- type -- data -- options +Specifically product analytics dashboards and visualizations make use of the `cube_analytics` data type. +The `cube_analytics` data type connects to the Cube instance defined when [product analytics was enabled](#enable-product-analytics). +All filters and queries are sent to the Cube instance and the returned data is processed by the +product analytics data source to be rendered by the appropriate visualizations. ## Funnel analysis diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index f405dc42f46..f2f1921f0bb 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -33,8 +33,9 @@ Prerequisite: To create a user manually: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select **New user**. 1. Complete the required fields, such as name, username, and email. 1. Select **Create user**. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index a2c82fdeadf..c367498f66e 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -17,19 +17,30 @@ Deleting a user deletes all projects in that user namespace. ## Delete your own account +> Delay between a user deleting their own account and deletion of the user record introduced in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. Enabled by default on GitLab.com. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. On GitLab.com, this feature is available. + As a user, to delete your own account: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. Select **Delete account**. +NOTE: +On GitLab.com, there is a seven day delay between a user deleting their own account and deletion of the user record. During this time, that user is [blocked](../../admin_area/moderate_users.md#block-a-user) and a new account with the same email address or username cannot be created. + +Unblocking the account does not undo the deletion because the account will still be in the deletion queue, and there is no quick method to reverse this process. + ## Delete users and user contributions **(FREE SELF)** As an administrator, to delete a user account: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: - **Delete user** to delete only the user but maintain their [associated records](#associated-records). You can't use this option if diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 8827e1e27c5..b856366bb58 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -108,7 +108,7 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Open the configuration file. - For Omnibus GitLab: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -123,7 +123,7 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Add the provider configuration: - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['forti_authenticator_enabled'] = true @@ -145,8 +145,9 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or - [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). +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). ### Enable one-time password using Duo @@ -174,7 +175,7 @@ On your GitLab server: 1. Open the configuration file. - For Omnibus GitLab: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -189,7 +190,7 @@ On your GitLab server: 1. Add the provider configuration: - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['duo_auth_enabled'] = false @@ -209,7 +210,7 @@ On your GitLab server: ``` 1. Save the configuration file. -1. For Omnibus GitLab, [reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). +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). ### Enable one-time password using FortiToken Cloud @@ -233,7 +234,7 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Open the configuration file. - For Omnibus GitLab: + For Linux package installations: ```shell sudo editor /etc/gitlab/gitlab.rb @@ -248,7 +249,7 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Add the provider configuration: - For Omnibus package: + For Linux package installations: ```ruby gitlab_rails['forti_token_cloud_enabled'] = true @@ -266,8 +267,8 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or - [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). +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). ### Set up a WebAuthn device diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index 1313c714dd0..4e3248ceb10 100644 --- a/doc/user/profile/achievements.md +++ b/doc/user/profile/achievements.md @@ -202,6 +202,36 @@ mutation { } ``` +## Delete an awarded achievement + +If you awarded an achievement to a user by mistake, you can delete it. + +Prerequisites: + +- You must have the Owner role for the namespace. + +To delete an awarded achievement, call the [`userAchievementsDelete` GraphQL mutation](../../api/graphql/reference/index.md#mutationuserachievementsdelete). + +```graphql +mutation { + userAchievementsDelete(input: { + userAchievementId: "gid://gitlab/Achievements::UserAchievement/<user achievement id>" }) { + userAchievement { + id + achievement { + id + name + } + user { + id + username + } + } + errors + } +} +``` + ## Delete an achievement If you consider you no longer need an achievement, you can delete it. @@ -230,7 +260,7 @@ mutation { If you don't want to display achievements on your profile, you can opt out. To do this: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, clear the **Display achievements on your profile** checkbox. 1. Select **Update profile settings**. diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index f22accf2ff5..cb56aa8a07a 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -16,7 +16,7 @@ review the sessions, and revoke any you don't recognize. To list all active sessions: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. @@ -33,7 +33,7 @@ exceeds 100, the oldest ones are deleted. To revoke an active session: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. 1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md index 8a94aff44fe..4157fc852b7 100644 --- a/doc/user/profile/comment_templates.md +++ b/doc/user/profile/comment_templates.md @@ -9,11 +9,11 @@ type: howto > - 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. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `saved_replies`. -On GitLab.com, this feature is not available by default, but enabled for GitLab team members. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `saved_replies`. +On GitLab.com, this feature is available. With comment templates, create and reuse text for any text area in: @@ -25,24 +25,22 @@ With comment templates, create and reuse text for any text area in: Comment templates can be small, like approving a merge request and unassigning yourself from it, or large, like chunks of boilerplate text you use frequently: -![Comment templates dropdown list](img/saved_replies_dropdown_v15_10.png) - -For more information about the rollout plan for this feature, see [issue 352956](https://gitlab.com/gitlab-org/gitlab/-/issues/352956). +![Comment templates dropdown list](img/saved_replies_dropdown_v16_0.png) ## Use comment templates in a text area To include the text of a comment template in your comment: -1. In the editor toolbar for your comment, select **Comment templates** (**{symlink}**). +1. In the editor toolbar for your comment, select **Comment templates** (**{comment-lines}**). 1. Select your desired comment template. ## Create comment templates To create a comment template for future use: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. From the dropdown list, select **Preferences**. -1. On the left sidebar, select **Comment templates** (**{symlink}**). +1. On the left sidebar, select **Comment templates** (**{comment-lines}**). 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. @@ -52,18 +50,18 @@ To create a comment template for future use: To go to your comment templates: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. From the dropdown list, select **Preferences**. -1. On the left sidebar, select **Comment templates** (**{symlink}**). +1. On the left sidebar, select **Comment templates** (**{comment-lines}**). 1. Scroll to **My comment templates**. ## Edit or delete comment templates To edit or delete a previously comment template: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. From the dropdown list, select **Preferences**. -1. On the left sidebar, select **Comment templates** (**{symlink}**). +1. On the left sidebar, select **Comment templates** (**{comment-lines}**). 1. Scroll to **My comment templates**, and identify the comment template you want to edit. 1. To edit, select **Edit** (**{pencil}**). 1. To delete, select **Delete** (**{remove}**), then select **Delete** again from the modal window. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index 7b5691e1ee5..7adf653606e 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -40,7 +40,7 @@ GitLab tracks the following contribution events: To view your daily contributions: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select your name from the dropdown list. 1. In the contributions calendar: - To view the number of contributions for a specific day, hover over a tile. @@ -53,7 +53,7 @@ The contributions calendar graph and recent activity list displays your To view private contributions: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -96,7 +96,7 @@ If you think your feed token has been exposed, you should reset it. To reset your feed token: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Scroll down. In the **Feed token** section, select the diff --git a/doc/user/profile/img/saved_replies_dropdown_v15_10.png b/doc/user/profile/img/saved_replies_dropdown_v15_10.png Binary files differdeleted file mode 100644 index 50313f71f4a..00000000000 --- a/doc/user/profile/img/saved_replies_dropdown_v15_10.png +++ /dev/null diff --git a/doc/user/profile/img/saved_replies_dropdown_v16_0.png b/doc/user/profile/img/saved_replies_dropdown_v16_0.png Binary files differnew file mode 100644 index 00000000000..4608484a496 --- /dev/null +++ b/doc/user/profile/img/saved_replies_dropdown_v16_0.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index b7d8f6aba58..958acaa61a9 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -15,14 +15,14 @@ Your profile also includes settings, which you use to customize your GitLab expe To access your profile: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select your name or username. ## Access your user settings To access your user settings: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. ## Change your username @@ -44,7 +44,7 @@ Prerequisites: To change your username: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Change username** section, enter a new username as the path. @@ -54,7 +54,7 @@ To change your username: To add new email to your account: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Emails**. 1. In the **Email** text box, enter the new email. @@ -67,7 +67,7 @@ You can make your user profile visible to only you and GitLab administrators. To make your profile private: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. Select the **Private profile** checkbox. 1. Select **Update profile settings**. @@ -104,8 +104,7 @@ the README file with information, it's included on your profile page. To create a new project and add its README to your profile: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name for your new project. @@ -133,7 +132,7 @@ They can help other users connect with you on other platforms. To add links to other accounts: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, add your: - Discord [user ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-). @@ -150,7 +149,7 @@ In the user contribution calendar graph and recent activity list, you can see yo To show private contributions: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -164,7 +163,7 @@ your name in your profile. To specify your pronouns: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Pronouns** text box, enter your pronouns. The text must be 50 characters or less. 1. Select **Update profile settings**. @@ -178,7 +177,7 @@ your name. To add your name pronunciation: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Pronunciation** text box, enter how your name is pronounced. The pronunciation must be plain text and 255 characters or less. 1. Select **Update profile settings**. @@ -194,7 +193,7 @@ Your status is publicly visible even if your [profile is private](#make-your-use To set your current status: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Set the desired emoji and status message. Status messages must be plain text and 100 characters or less. They can also contain emoji codes like, `I'm on vacation :palm_tree:`. @@ -217,12 +216,12 @@ To indicate to others that you are busy, you can set an indicator. To set the busy status indicator, either: - Set it directly: - 1. On the top bar, in the upper-right corner, select your avatar. + 1. On the left sidebar, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Select the **Set yourself as busy** checkbox. - Set it on your profile: - 1. On the top bar, in the upper-right corner, select your avatar. + 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Current status** section, select the **Set yourself as busy** checkbox. @@ -238,7 +237,7 @@ You can set your local time zone to: To set your time zone: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Time settings** section, select your time zone from the dropdown list. @@ -284,7 +283,7 @@ so you can keep your email information private. To use a private commit email: -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Commit email** dropdown list, select **Use a private email**. 1. Select **Update profile settings**. @@ -315,7 +314,7 @@ the maximum number of users you can follow is 300. You can disable following and being followed by other users. -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. Select **Preferences**. 1. Clear the **Enable follow users** checkbox. @@ -324,6 +323,20 @@ You can disable following and being followed by other users. NOTE: When this feature is being disabled, all current followed/following connections are deleted. +## Advanced code search with zoekt + +### Disable searching code with zoekt + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388519) as a beta feature [with a flag](../feature_flags.md) named `search_code_with_zoekt`. Enabled by default. + +You can disable searching with Zoekt and use Elasticsearch instead. + +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **Preferences**. +1. Clear the **Enable advanced code search** checkbox. +1. Select **Save changes**. + ## View your activity GitLab tracks [user contribution activity](contributions_calendar.md). @@ -363,7 +376,7 @@ When you sign in, three cookies are set: - A session cookie called `_gitlab_session`. This cookie has no set expiration date. However, it expires based on its `session_expire_delay`. -- A session cookied called `about_gitlab_active_user`. +- A session cookie called `about_gitlab_active_user`. This cookie is used by the [marketing site](https://about.gitlab.com/) to determine if a user has an active GitLab session. No user information is passed to the cookie and it expires with the session. - A persistent cookie called `remember_user_token`, which is set only if you selected **Remember me** on the sign-in page. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index b60ff8471bf..cc0b67eed52 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -107,7 +107,7 @@ To select a notification level for a group, use either of these methods: Or: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select the notification dropdown list, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). @@ -138,7 +138,7 @@ To select a notification level for a project, use either of these methods: Or: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select the notification dropdown list, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). @@ -263,7 +263,7 @@ epics: | Issue | Reassigned | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | | Issue | Reopened | Subscribers and participants. | | Merge Request | Closed | Subscribers and participants. | -| Merge Request | Conflict | Author and any user that has set the merge request to automatically merge when pipeline succeeds. | +| Merge Request | Conflict | Author and any user that has set the merge request to auto-merge. | | Merge Request | [Marked as ready](../project/merge_requests/drafts.md) | Watchers and participants. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15332) in GitLab 13.10._ | | Merge Request | Merged | Subscribers and participants. | | Merge Request | Merged when pipeline succeeds | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4._ | diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index e59d7313281..bda92ce8388 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -86,7 +86,12 @@ At any time, you can revoke a personal access token. ## View the last time a token was used -Token usage information is updated every 24 hours. GitLab considers a token used when the token is used to: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414945) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `update_personal_access_token_usage_information_every_10_minutes`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `update_personal_access_token_usage_information_every_10_minutes`. On GitLab.com, this feature is available. + +Token usage information is updated every 10 minutes. GitLab considers a token used when the token is used to: - Authenticate with the [REST](../../api/rest/index.md) or [GraphQL](../../api/graphql/index.md) APIs. - Perform a Git operation. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index da4d2da70fe..bcfe323a5fe 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -39,11 +39,11 @@ The default theme is Indigo. You can choose between 10 themes: ## Dark mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](../../policy/alpha-beta-support.md#experiment) release. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Experiment](../../policy/experiment-beta-support.md#experiment) release. 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/alpha-beta-support.md#experiment). +[Experiment features](../../policy/experiment-beta-support.md#experiment). Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: @@ -129,6 +129,8 @@ You can choose between 2 options: The **Project overview content** setting allows you to choose what content you want to see on a project's home page. +If **Files and Readme** is selected, you can show or hide the shortcut buttons above the file list on the project overview with the **Show shortcut buttons above files on project overview** setting. + ### Tab width You can set the displayed width of tab characters across various parts of @@ -182,6 +184,13 @@ NOTE: This feature is experimental, and choosing absolute times might break certain layouts. Open an issue if you notice that using absolute times breaks a layout. +## User identities in CI job JSON web tokens + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0. False by default. + +You can select to include the list of your external identities in the JSON Web Token information that is generated for a CI job. +For more information and examples, see [Token Payload](../../ci/secrets/id_token_authentication.md#token-payload). + ## Integrations Configure your preferences with third-party services which provide enhancements to your GitLab experience. diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index eac3db3c71c..50624a43893 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -23,18 +23,29 @@ authorization provider, you do not need to choose a password. GitLab ## Change your password +> Password reset emails sent to any verified email address [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16311) in GitLab 16.1. + You can change your password. GitLab enforces [password requirements](#password-requirements) when you choose your new password. -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Password**. 1. In the **Current password** text box, enter your current password. 1. In the **New password** and **Password confirmation** text box, enter your new password. 1. Select **Save password**. -If you don't know your current password, select the **I forgot my password** link. A password reset email is sent to the -account's **primary** email address. +If you do not know your current password, select **I forgot my password** +and complete the form. A password reset email is sent to the email address you +enter into this form, provided that the email address is verified. If you enter an +unverified email address into this form, no email is sent, and you see the following +message: + +> "If your email address exists in our database, you will receive a password recovery link at your email address in a few minutes." + +NOTE: +Your account can have more than one verified email address, and any email address +associated with your account can be verified. ## Password requirements diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 26708dece50..be47d6f18bd 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -130,8 +130,8 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Badges**. 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. @@ -151,8 +151,8 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter _Pipeline Status_. 1. Under **Link**, enter the following URL: @@ -180,8 +180,8 @@ If you need individual badges for each project, either: To add a new badge to a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under "Badge image URL" the URL of the image that should be displayed. @@ -202,8 +202,8 @@ Badges associated with a group can be edited or deleted only at the [group level You can view the exact link for your badges. Then you can use the link to embed the badge in your HTML or Markdown pages. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. @@ -269,8 +269,9 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge with a custom image to a group or project: -1. On the top bar, select **Main menu** and find your group or project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or + group. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter the name for the badge. 1. Under **Link**, enter the URL that the badge should point to. diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index 7e622110291..0c12f7d476b 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -56,41 +56,56 @@ Changelog: feature ## Create a changelog -To generate changelog data based on commits in a repository, see +Changelogs are generated from the command line, using either the API or the +GitLab CLI. The changelog output is formatted in Markdown, and +[you can customize it](#customize-the-changelog-output). + +### From the API + +To generate changelogs via the API with a `curl` command, see [Add changelog data to a changelog file](../../api/repositories.md#add-changelog-data-to-a-changelog-file) in the API documentation. -The changelog output is formatted in Markdown, and [you can customize it](#customize-the-changelog-output). +### From the GitLab CLI -### Reverted commits +> [Introduced](https://gitlab.com/gitlab-org/cli/-/merge_requests/1222) in `glab` version 1.30.0. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. +Prerequisites: -To be treated as a revert commit, the commit message must contain the string -`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. +- You have installed and configured the [GitLab CLI](../../integration/glab/index.md), + version 1.30.0 or later. +- Your repository's tag naming schema matches + [the expected tag naming format](#customize-the-tag-format-when-extracting-versions). +- Commits include [changelog trailers](../../development/changelog.md). -When generating a changelog for a range, GitLab ignores commits both added and -reverted in that range. In this example, commit C reverts commit B. Because -commit C has no other trailer, only commit A is added to the changelog: +To generate the changelog: -```mermaid -graph LR - A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] - B --> C[Commit C<br>Reverts commit B] -``` +1. Update your local copy of your repository with `git fetch`. +1. To generate a changelog for the current version (as determined by `git describe --tags`) + with the default options: + - Run the command `glab changelog generate`. + - To save the output to a file, run the command `glab changelog generate > <filename>.md`. +1. To generate a changelog with customized options, run the command `glab changelog generate` + and append your desired options. Some options include: -However, if the revert commit (commit C) _also_ contains a changelog trailer, -both commits A and C are included in the changelog: - -```mermaid -graph LR - A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] - B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] -``` + - `--config-file [string]`: The path to the changelog configuration file in your project's + Git repository. Defaults to `.gitlab/changelog_config.yml`. + - Commit range: + - `--from [string]`: The start of the range of commits (as a SHA) to use for + generating the changelog. This commit itself isn't included in the changelog. + - `--to [string]`: The end of the range of commits (as a SHA) to use for + generating the changelog. This commit _is_ included in the list. Defaults to the `HEAD` + of the default project branch. + - `--date [string]`: The date and time of the release, in ISO 8601 (`2016-03-11T03:45:40Z`) + format. Defaults to the current time. + - `--trailer [string]`: The Git trailer to use for including commits. Defaults to `Changelog`. + - `--version [string]`: The version to generate the changelog for. -Commit B is skipped. +To learn more about the parameters available in GitLab CLI, run `glab changelog generate --help`. See the +[API documentation](../../api/repositories.md#add-changelog-data-to-a-changelog-file) +for definitions and usage. -### Customize the changelog output +## Customize the changelog output To customize the changelog output, edit the changelog configuration file. The default location for this configuration is `.gitlab/changelog_config.yml`. The file supports @@ -311,6 +326,34 @@ To test if your regular expression is working, you can use websites such as [regex101](https://regex101.com/). If the regular expression syntax is invalid, an error is produced when generating a changelog. +## Reverted commit handling + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. + +To be treated as a revert commit, the commit message must contain the string +`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. + +When generating a changelog for a range, GitLab ignores commits both added and +reverted in that range. In this example, commit C reverts commit B. Because +commit C has no other trailer, only commit A is added to the changelog: + +```mermaid +graph LR + A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B] +``` + +However, if the revert commit (commit C) _also_ contains a changelog trailer, +both commits A and C are included in the changelog: + +```mermaid +graph LR + A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] +``` + +Commit B is skipped. + ## Related topics - [Changelog-related endpoints](../../api/repositories.md) in the Repositories API diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 6c8edb8c3e5..87554e786ab 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -174,7 +174,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#gitlab-agent-for-kubernetes-supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -248,7 +248,10 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. In GitLab, on the top bar, select **Main menu > Admin > Settings > General** and expand the **Amazon EKS** section. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Amazon EKS**. 1. Check **Enable Amazon EKS integration**. 1. Enter your **Account ID**. 1. Enter your [access key and ID](#eks-access-key-and-id). diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 31d5a73757a..2ea7ac0f1fd 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -78,7 +78,7 @@ You can customize the deployment namespace in a few ways: - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, but the user is responsible for ensuring its existence. You can fully customize this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments-deprecated) + [`environment:kubernetes:namespace`](../../../ci/environments/configure_kubernetes_deployments.md) in `.gitlab-ci.yml`. When you customize the namespace, existing environments remain linked to their current diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 5ce1994ba36..ab6084acd5e 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -24,5 +24,5 @@ to a single project. To view project-level Kubernetes clusters: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Kubernetes clusters**. diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index e69dba6f977..272d59bd6a4 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -48,8 +48,8 @@ For example: To view the Code Owners of a file or directory: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Go to the file or directory you want to see the Code Owners for. 1. Optional. Select a branch or tag. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 13ee07097e1..5bd19fec0ba 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -56,14 +56,14 @@ As with all sensitive information, you should ensure only those who need access For human interactions, use credentials tied to users such as Personal Access Tokens. To help detect a potential secret leak, you can use the -[Audit Event](../../../administration/audit_event_streaming.md#example-payloads-for-ssh-events-with-deploy-key) feature. +[Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-ssh-events-with-deploy-key) feature. ## View deploy keys To view the deploy keys available to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Deploy keys**. The deploy keys available are listed: @@ -80,8 +80,8 @@ Prerequisites: - [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. Complete the fields. 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** @@ -101,8 +101,9 @@ Prerequisites: To create a public deploy key: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Deploy Keys**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Deploy Keys**. 1. Select **New deploy key**. 1. Complete the fields. - Use a meaningful description for **Name**. For example, include the name of the external host @@ -118,8 +119,8 @@ Prerequisites: To grant a public deploy key access to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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 **Publicly accessible deploy keys**. 1. In the key's row, select **Enable**. @@ -138,8 +139,8 @@ Prerequisites: To disable a deploy key: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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 **Disable** (**{cancel}**). @@ -160,7 +161,7 @@ There are a few scenarios where a deploy key fails to push to a - The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. -- **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#configure-a-protected-branch) of the protected branch. +- **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#add-protection-to-existing-branches) of the protected branch. All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index a81ccd043bd..0b9c42f2a60 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -92,10 +92,8 @@ Prerequisites: - You must have at least the Maintainer role for the project or group. -1. On the top bar, select **Main menu**, and: - - For a project deploy token, select **Projects** and find your project. - - For a group deploy token, select **Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +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. Complete the fields, and select the desired [scopes](#scope). 1. Select **Create deploy token**. @@ -113,10 +111,8 @@ Prerequisites: To revoke a deploy token: -1. On the top bar, select **Main menu**, and: - - For a project deploy token, select **Projects** and find your project. - - For a group deploy token, select **Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +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. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index f0ced95c8eb..11e538964a2 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -32,8 +32,8 @@ directory in your repository. To create an issue description template: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. 1. Next to the default branch, in the **File name** text box, enter `.gitlab/issue_templates/mytemplate.md`, @@ -52,8 +52,8 @@ that depend on the contents of commit messages and branch names. To create a merge request description template for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. 1. Next to the default branch, in the **File name** text box, enter `.gitlab/merge_request_templates/mytemplate.md`, @@ -118,14 +118,14 @@ that you can use when creating a new project in the instance. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. -With **group-level** description templates, you can store your templates in a single repository and -configure the group file templates setting to point to that repository. +With **group-level** description templates, you can select a repository within the group to store +your templates. Then, you can access these templates from other projects in the group. As a result, you can use the same templates in issues and merge requests in all the group's projects. To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Templates**. 1. From the dropdown list, select your template project as the template repository at group level. 1. Select **Save changes**. @@ -155,8 +155,8 @@ To set a default description template for merge requests, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > Merge requests**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > Merge requests**. 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. @@ -167,8 +167,8 @@ To set a default description template for issues, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > General**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > General**. 1. Expand **Default description template for issues**. 1. Fill in the text area. 1. Select **Save changes**. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index c81ba4b7dd3..71b4bff41d1 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -219,8 +219,8 @@ To view the user who locked the file (if it was not you), hover over the button. To view and remove file locks: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Locked files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Locked files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index b523e007f0e..dc17a3646a8 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -70,8 +70,7 @@ For user contributions to be mapped, each user must complete the following befor > Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. 1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **Bitbucket Cloud**. 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 4d3a6eb87e0..fce9ca7d147 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -41,8 +41,7 @@ You can import Bitbucket repositories to GitLab. To import your Bitbucket repositories: 1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **Bitbucket Server**. 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 692ec1390d2..30c4249e0d6 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -29,8 +29,7 @@ users. To import your project from FogBugz: 1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **FogBugz**. 1. Enter your FogBugz URL, email address, and password. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index b2b1ede12d4..509029a3099 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -17,9 +17,11 @@ The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or `gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to different namespaces. -If you are importing to a self-managed GitLab instance, you can use the -[GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects -without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. +- If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. The + Rake task imports projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. +- If you are importing from GitHub Enterprise to GitLab.com, use the + [GitLab Import API](../../../api/import.md#import-repository-from-github) GitHub endpoint instead. This allows you to provide a different domain to import the project from. + Using the UI, the GitHub importer always imports from the `github.com` domain. When importing projects: @@ -30,6 +32,7 @@ When importing projects: - The importer also imports branches on forks of projects related to open pull requests. These branches are imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to a discrepancy in branches compared to those of the GitHub repository. +- The organization the repository belongs to must not impose restrictions of a [third-party application access policy](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) on the GitLab instance you import to. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview of the import process, see [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). @@ -137,11 +140,12 @@ Use one of the following tabs to filter the list of repositories: - **Collaborated**: Filter the list to the repositories that you have contributed to. - **Organization**: Filter the list to the repositories that belong to an organization you are a member of. -When the **Organization** tab is selected, you can further narrow down your search by selecting an available GitHub organization from a dropdown. +When the **Organization** tab is selected, you can further narrow down your search by selecting an available GitHub organization from a dropdown list. ### Select additional items to import -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5. +> - Importing collaborators as an additional item was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398154) in GitLab 16.0. To make imports as fast as possible, the following items aren't imported from GitHub by default: @@ -183,17 +187,17 @@ To open an repository in GitLab URL after it has been imported, select its GitLa Completed imports can be re-imported by selecting **Re-import** and specifying new name. This creates a new copy of the source project. -![GitHub importer page](img/import_projects_from_github_importer_v12_3.png) +![GitHub importer page](img/import_projects_from_github_importer_v16_0.png) ### Check status of imports -> Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.0. +> Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.1. After imports are completed, they can be in one of three states: -- **Completed**: GitLab imported all repository entities. +- **Complete**: GitLab imported all repository entities. - **Partially completed**: GitLab failed to import some repository entities. -- **Failed**: GitLab imported no repository entities. +- **Failed**: GitLab aborted the import after a critical error occurred. Expand **Details** to see a list of [repository entities](#imported-data) that failed to import. @@ -280,12 +284,12 @@ When they are imported, supported GitHub branch protection rules are mapped to e | GitHub rule | GitLab rule | Introduced in | | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | -| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | -| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | +| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | +| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | | **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | | **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | | **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue diff --git a/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png b/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png Binary files differdeleted file mode 100644 index 3ac03c0ecc5..00000000000 --- a/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/img/import_projects_from_github_importer_v16_0.png b/doc/user/project/import/img/import_projects_from_github_importer_v16_0.png Binary files differnew file mode 100644 index 00000000000..190474c4d89 --- /dev/null +++ b/doc/user/project/import/img/import_projects_from_github_importer_v16_0.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 1265b8534d0..9fdb8eed5aa 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -18,7 +18,7 @@ For any type of source and target, you can migrate GitLab projects: - When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in - [Beta](../../../policy/alpha-beta-support.md#beta). The feature is not ready for production use. + [Beta](../../../policy/experiment-beta-support.md#beta). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. @@ -26,7 +26,7 @@ If you only need to migrate Git repositories, you can [import each project by UR import issues and merge requests this way. To retain metadata like issues and merge requests, either: - [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). - This feature is in [Beta](../../../policy/alpha-beta-support.md#beta). It is not ready for production use. + This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -41,8 +41,9 @@ with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate gro GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. 1. Clear checkboxes for importers that are not required. @@ -113,8 +114,7 @@ You can view all project imports created by you. This list includes the followin To view project import history: 1. Sign in to GitLab. -1. On the top bar, select **Create new...** (**{plus-square}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 4ad51ccb97f..230113581f8 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -19,7 +19,8 @@ You can import your existing repositories by providing the Git URL. ## Import project by URL -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 1512039fb25..67b96efe9a4 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -12,8 +12,7 @@ You can create a project in many ways in GitLab. To create a blank project: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. @@ -42,8 +41,7 @@ Anyone can [contribute a built-in template](../../development/project_templates. To create a project from a built-in template: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: @@ -73,8 +71,7 @@ Custom project templates are available at: - The [instance-level](../../user/admin_area/custom_project_templates.md) - The [group-level](../../user/group/custom_project_templates.md) -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: @@ -99,8 +96,7 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service To create a project from the HIPAA Audit Protocol template: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: @@ -138,7 +134,7 @@ Prerequisites: [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the top bar, select **Main menu > Groups** and find your group. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. In the upper-right corner, confirm that **New project** is visible. Contact your GitLab administrator if you require permission. diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 2874bf98736..5ca6fcebdd6 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -24,8 +24,8 @@ Prerequisites: To view project insights: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Insights**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Insights**. 1. To view a report, select the **Select report** dropdown list. ## Configure project insights @@ -45,7 +45,7 @@ To configure project insights, either: - Create a `.gitlab/insights.yml` file locally in the root directory of your project, and push your changes. - Create a `.gitlab/insights.yml` file in the UI: - 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Above the file list, select the branch you want to commit to, select the plus icon, then select **New file**. 1. In the **File name** text box, enter `.gitlab/insights.yml`. 1. In the large text box, update the file contents. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 633d565064c..405531abd0d 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -29,14 +29,15 @@ An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.co GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: 1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. -1. Select **Apple App Store**. +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. 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. - **Private Key**: The generated private key. You can download this key only once. + - **Protected branches and tags only**: Enable to only set variables on protected branches and tags. 1. Select **Save changes**. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index b1a4d2a2f78..edd08f1e3d3 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,13 +32,14 @@ In Asana, create a Personal Access Token. Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Asana. 1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. <!-- ## Troubleshooting --> diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 23990036f4e..8394687d8f5 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -36,8 +36,8 @@ integration in GitLab. ## Configure GitLab -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. 1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. @@ -47,8 +47,7 @@ integration in GitLab. 1. If necessary, enter a username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require authentication. -1. Optional. To test the configuration and trigger a build in Bamboo, - select **Test Settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. ### Identify the Bamboo build plan build key diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index f2af4dc6e4d..1796e674b00 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,8 +14,8 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Fill in the required fields: @@ -31,7 +31,8 @@ To enable the Bugzilla integration in a project: For example, for a project named "My Cool App": `https://bugzilla.example.org/enter_bug.cgi#h=dupes%7CMy+Cool+App`. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After you configure and enable Bugzilla, a link appears on the GitLab project pages. This link takes you to the appropriate Bugzilla project. diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md new file mode 100644 index 00000000000..bf2c738049c --- /dev/null +++ b/doc/user/project/integrations/clickup.md @@ -0,0 +1,54 @@ +--- +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 +--- + +# ClickUp **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1. + +You can use [ClickUp](https://clickup.com/) as an external issue tracker. +To enable the ClickUp integration in a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **ClickUp**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: + + - **Project URL**: The URL to the ClickUp project to link to this GitLab project. + - **Issue URL**: The URL to the ClickUp project issue to link to this GitLab project. + The URL must contain `:id`. GitLab replaces this ID with the issue number. + +1. Optional. Select **Test settings**. +1. Select **Save changes**. + +After you have configured and enabled ClickUp, you see the ClickUp link on the GitLab project pages, +which takes you to your ClickUp project. + +For example, this is a configuration for a project named `gitlab-ci`: + +- Project URL: `https://app.clickup.com/1234567` +- Issue URL: `https://app.clickup.com/t/:id` + +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). + +## Reference ClickUp issues in GitLab + +You can reference your ClickUp issues using: + +- `#<ID>`, where `<ID>` is a alphanumerical string (example `#8wrtcd932`). +- `CU-<ID>`, where `<ID>` is a alphanumerical string (example `CU-8wrtcd932`). +- `<PROJECT>-<ID>`, for example `API_32-143`, where: + - `<PROJECT>` is a ClickUp list custom prefix ID. + - `<ID>` is a number. + +In links, the `CU-` part is ignored and it links to the global URL of the issue. When a custom +prefix is used in a ClickUp list, the prefix part is part of the link. + +We suggest using the `CU-` format (`CU-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index b529d728e3b..9580c924fd1 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -20,8 +20,8 @@ on the left sidebar in your project. To enable a custom issue tracker in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Fill in the required fields: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 60b37f07bb5..180e39e3254 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -26,8 +26,8 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 7f8755f1114..eb3eecaa656 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -11,8 +11,8 @@ that is pushed to your project. To enable emails on push: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Emails on push**. 1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. 1. Configure the following options: diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 39dd548e7ca..d96558579d1 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,8 +14,8 @@ This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.n To enable the EWM integration, in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Fill in the required fields: @@ -35,7 +35,8 @@ To enable the EWM integration, in a project: Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem`. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Reference EWM work items in commit messages diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3e75106a9bc..98654a3b59f 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -29,8 +29,8 @@ Complete these steps on GitHub: Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **GitHub**. 1. Ensure the **Active** checkbox is selected. 1. In **Token**, paste the token you generated on GitHub. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index fabdf07f76f..8790c7213e5 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -107,8 +107,9 @@ With Slack notifications, GitLab can send messages to Slack workspace channels f To configure Slack notifications: -1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been [installed](#installation). -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for + which the GitLab for Slack app has been [installed](#installation). +1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. In the **Trigger** section, select the checkbox for each GitLab event you want to receive a notification for in Slack. For a full list, see @@ -162,8 +163,9 @@ New releases of the app might require permissions to be authorized before some f To update your GitLab for Slack app: -1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been configured. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for + which the GitLab for Slack app has been configured. +1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. Select **Reinstall GitLab for Slack app**. diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 2ae5a504e06..4b0f4fe205a 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -29,8 +29,8 @@ Prerequisites: To enable the Google Play integration in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 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`). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 3470d11b983..4046869072d 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -12,11 +12,11 @@ Hangouts). ## Integration workflow -To enable this integration, first you need to create a webhook for the room in +To enable this integration, you must first create a webhook for the space in Google Chat where you want to receive the notifications from your project. After that, enable the integration in GitLab and choose the events you want to -be notified about in your Google Chat room. +be notified about in your Google Chat space. For every selected event in your project, GitLab acts like a bot sending notifications to Google Chat: @@ -27,9 +27,9 @@ notifications to Google Chat: To enable the integration in Google Chat: -1. Enter the room where you want to receive notifications from GitLab. -1. In the upper-left corner, from the room dropdown list, select **Manage webhooks**. -1. Enter the name for your webhook, for example "GitLab integration". +1. Enter the space where you want to receive notifications from GitLab. +1. In the upper-left corner, from the space dropdown list, select **Apps and Integrations > Manage webhooks**. +1. Enter the name for your webhook (for example, `GitLab integration`). 1. Optional. Add an avatar for your bot. 1. Select **Save**. 1. Copy the webhook URL. @@ -40,6 +40,10 @@ For further details, see [the Google Chat documentation for configuring webhooks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27823) in GitLab 15.4. +WARNING: +In March 2023, Google [deprecated threaded replies in Google Chat](https://workspaceupdates.googleblog.com/2023/02/new-google-chat-spaces-will-be-in-line-threaded.html). +This feature does not work for new Google Chat spaces. You can still use this feature in existing Google Chat spaces where threaded replies are already enabled. + To enable threaded notifications for the same GitLab object (for example, an issue or merge request): 1. Go to [Google Chat](https://chat.google.com/). @@ -56,9 +60,9 @@ To enable the integration in GitLab: 1. In your project, go to **Settings > Integrations** and select **Google Chat**. 1. Scroll down to the end of the page where you find a **Webhook** field. 1. Enter the webhook URL you copied from Google Chat. -1. Select the events you want to be notified about in your Google Chat room. -1. Optional. Select **Test settings** to verify the connection. +1. Select the events you want to be notified about in your Google Chat space. +1. Optional. Select **Test settings**. 1. Select **Save changes**. To test the integration, make a change based on the events you selected and -see the notification in your Google Chat room. +see the notification in your Google Chat space. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 4a586054aee..12986cba555 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -25,8 +25,8 @@ In the Harbor instance, ensure that: GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Provide the Harbor configuration information: diff --git a/doc/user/project/integrations/img/merge_request_performance.png b/doc/user/project/integrations/img/merge_request_performance.png Binary files differdeleted file mode 100644 index a9cd761cdcb..00000000000 --- a/doc/user/project/integrations/img/merge_request_performance.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard.png b/doc/user/project/integrations/img/prometheus_dashboard.png Binary files differdeleted file mode 100644 index 24d855eb50c..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_manual_configuration_v13_2.png b/doc/user/project/integrations/img/prometheus_manual_configuration_v13_2.png Binary files differdeleted file mode 100644 index b6ec08f492d..00000000000 --- a/doc/user/project/integrations/img/prometheus_manual_configuration_v13_2.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index f7019b2eeb2..c70a58a24d2 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -18,8 +18,8 @@ Prerequisites: To view the available integrations for your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. You can also view and manage integration settings across [all projects in an instance or group](../../admin_area/settings/project_integration_management.md). For a single project, you can choose to inherit the instance or group configuration, @@ -50,6 +50,7 @@ You can configure the following integrations. | [Bugzilla](bugzilla.md) | Use Bugzilla as the issue tracker. | **{dotted-circle}** No | | Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | | Campfire | Connect to chat. | **{dotted-circle}** No | +| [ClickUp](clickup.md) | Use ClickUp as the issue tracker. | **{dotted-circle}** No | | [Confluence Workspace](../../../api/integrations.md#confluence-integration) | Use Confluence Cloud Workspace as an internal wiki. | **{dotted-circle}** No | | [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | | [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | **{check-circle}** Yes | @@ -80,6 +81,7 @@ You can configure the following integrations. | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in 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 | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index df11ed3e57c..7d3c85b2c62 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,8 +39,8 @@ network. For more details, read ## Complete these steps in GitLab -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. 1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty, @@ -50,8 +50,9 @@ network. For more details, read It's prepended to every channel or user provided under **Recipients**, which is not a full URI. 1. Under **Recipients**, enter the users or channels to receive updates, separated by spaces (for example, `#channel1 user1`). For more details, see [Enter irker recipients](#enter-irker-recipients). -1. Optional. Under **Colorize messages**, select the checkbox. irker will highlight your messages. -1. Select **Save changes** or optionally select **Test Settings**. +1. Optional. To highlight messages, select the **Colorize messages** checkbox. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Enter irker recipients diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index a50d341c38e..a73c0f001f3 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -41,8 +41,8 @@ Display name override is not enabled by default, you need to ask your administra After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Mattermost notifications**. 1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel to receive the notification. You do not need to add the hash sign (`#`). diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 3b5e4030487..a8d8323a651 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -17,9 +17,9 @@ separately configured [Mattermost notifications](mattermost.md). GitLab provides different ways to configure Mattermost slash commands. For any of these options, you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/). -- **Omnibus GitLab installations**: Mattermost is bundled with - [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, - read the [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). +- **Linux package installations**: Mattermost is bundled with + [Linux package](https://docs.gitlab.com/omnibus/). To configure Mattermost for Linux package + installations, read the [Linux package Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the [automated configuration](#configure-automatically). - **For all other installations**, use the [manual configuration](#configure-manually). @@ -29,9 +29,9 @@ you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/pla If Mattermost is installed on the same server as GitLab, you can automatically configure Mattermost slash commands: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **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. Select **Add to Mattermost**, and select **Save changes**. @@ -65,8 +65,9 @@ To get configuration values from GitLab: 1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. 1. Copy the **Request URL** value. All other values are suggestions. 1. Do not close this browser tab. You need it in a later step. @@ -133,7 +134,7 @@ The available slash commands for Mattermost are: ## Related topics - [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) -- [Omnibus GitLab Mattermost](../../../integration/mattermost/index.md) +- [Linux package Mattermost](../../../integration/mattermost/index.md) ## Troubleshooting diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 5d2c27fc2a4..3d0b77069a3 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -35,8 +35,8 @@ After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Microsoft Teams notifications**. 1. To enable the integration, select **Active**. 1. In the **Trigger** section, select the checkbox next to each event to enable it: diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index 75fae4647d0..cffa2649cc8 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -6,10 +6,10 @@ info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering pr # MLflow client integration **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. +> [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. NOTE: -Model experiment tracking is an [experimental feature](../../../policy/alpha-beta-support.md). +Model experiment tracking is an [experimental feature](../../../policy/experiment-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. [MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. @@ -23,7 +23,9 @@ GitLab plays the role of a MLflow server. Running `mlflow server` is not necessa Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) for the project, with minimum access level of `api`. -- The project ID. To find the project ID, on the top bar, select **Main menu > Projects** and find your project. On the left sidebar, select **Settings > General**. +- The project ID. To find the project ID: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > General**. To enable MLflow client integration: diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index e1d48037ba8..7f53f08e808 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,11 +37,12 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Pivotal Tracker. 1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index e05ff9489ca..62703ebfad9 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -26,14 +26,15 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. 1. To enable the integration for your instance: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Pumble. 1. Paste the **Webhook** URL for the Pumble channel. 1. Configure the remaining options. -1. Optional. To test the integration, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. The Pumble channel begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index df8a6681e2b..9cb93c2d082 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -9,8 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Fill in the required fields: @@ -24,7 +24,8 @@ To enable the Redmine integration in a project: **This URL is not used and removal is planned in a future release.** For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages, which takes you to your Redmine project. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index cf9745929a1..6fbd246d7f4 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -21,11 +21,11 @@ This change is a breaking change. ## Configure settings in GitLab -To enable the Shimo integration for your group or project: +To enable the Shimo integration for your project: -1. On the top bar, select **Main menu** and find your group or project. -1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **Shimo**. +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. 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**. @@ -36,8 +36,8 @@ On the left sidebar, **Shimo** now appears instead of **Wiki**. To view the Shimo Workspace from your group or project: -1. On the top bar, select **Main menu** and find your group or project. -1. On the left sidebar, select **Shimo**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. <!--- end_remove --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5b769b84663..14183a47625 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -32,8 +32,8 @@ to control GitLab from Slack. Slash commands are configured separately. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. In the **Trigger** section, select the checkboxes for each type of GitLab @@ -56,8 +56,8 @@ to control GitLab from Slack. Slash commands are configured separately. 1. Leave the **Labels to be notified** field blank to get all notifications, or add labels that the issue or merge request must have to trigger a notification. -1. Select **Test settings** to verify your information, and then select - **Save changes**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 4fa4b75422e..74bd12561fb 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -19,11 +19,10 @@ The [Slack notifications integration](slack.md) is configured separately. ## Configure GitLab and Slack -Slack slash command integrations -are scoped to a project. +Slack slash command integrations are scoped to a project. -1. In GitLab, on the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index 2a1106edb0c..ff633783e83 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -26,8 +26,8 @@ are synchronized as requirements in Squash TM and test progress is reported in G ## Configure GitLab -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Squash TM**. 1. Ensure that the **Active** toggle is enabled. 1. In the **Trigger** section, indicate which type of issue is concerned by the real-time synchronization. diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md new file mode 100644 index 00000000000..9d36a16f5fc --- /dev/null +++ b/doc/user/project/integrations/telegram.md @@ -0,0 +1,57 @@ +--- +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 +--- + +# Telegram **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122879) in GitLab 16.1. + +You can configure GitLab to send notifications to a Telegram chat or channel. +To set up the Telegram integration, you must: + +1. [Create a Telegram bot](#create-a-telegram-bot). +1. [Configure the Telegram bot](#configure-the-telegram-bot). +1. [Set up the Telegram integration in GitLab](#set-up-the-telegram-integration-in-gitlab). + +## Create a Telegram bot + +To create a bot in Telegram: + +1. Start a new chat with `@BotFather`. +1. [Create a new bot](https://core.telegram.org/bots/features#creating-a-new-bot) as described in the Telegram documentation. + +When you create a bot, `BotFather` provides you with an API token. Keep this token secure as you need it to authenticate the bot in Telegram. + +## Configure the Telegram bot + +To configure the bot in Telegram: + +1. Add the bot as an administrator to a new or existing channel. +1. Assign the bot `Post Messages` rights to receive events. +1. Create an identifier for the channel. + - For public channels, enter a public link and copy the channel identifier (for example, `https:/t.me/MY_IDENTIFIER`). + - For private channels, use the [`getUpdates`](https://telegram-bot-sdk.readme.io/reference/getupdates) method with your API token and copy the channel identifier. + +## Set up the Telegram integration in GitLab + +After you invite the bot to a Telegram channel, you can configure GitLab to send notifications: + +1. To enable the integration: + - **For your group or project:** + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. Select **Settings > Integrations**. + - **For your instance:** + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Settings > Integrations**. +1. Select **Telegram**. +1. In **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). +1. Optional. Select **Test settings**. +1. Select **Save changes**. + +The Telegram channel can now receive all selected GitLab events. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index d20b19a3aaa..7d0dd6d2af3 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,14 +15,15 @@ copy its URL. In GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. 1. In the **Branches for which notifications are to be sent** dropdown list, select which types of branches to send notifications for. -1. Select `Save changes` or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. Your Unify Circuit conversation now starts receiving GitLab event notifications. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index c755c7a5c17..3ba05476e63 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -21,18 +21,22 @@ You can configure GitLab to send notifications to a Webex Teams space: ## Configure settings in GitLab -Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send +After you have a webhook URL for your Webex Teams space, you can configure GitLab to send notifications: -1. Navigate to: - - **Settings > Integrations** in a project to enable the integration at the project level. - - **Settings > Integrations** in a group to enable the integration at the group level. - - On the top bar, select **Main menu > Admin**. Then, in the left sidebar, - select **Settings > Integrations** to enable an instance-level integration. +1. To enable integration: + - At the project or group level: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. Select **Settings > Integrations**. + - At the instance level: + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Settings > Integrations**. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. 1. Paste the **Webhook** URL for the Webex Teams space. -1. Configure the remaining options and then select **Test settings and save changes**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. The Webex Teams space begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index fda778aa167..dfff537e4a1 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -786,7 +786,7 @@ Payload example: "noteable_id": 53, "system": false, "st_diff": null, - "url": "http://example.com/gitlab-org/gitlab-test/snippets/53#note_1245" + "url": "http://example.com/gitlab-org/gitlab-test/-/snippets/53#note_1245" }, "snippet": { "id": 53, @@ -799,7 +799,8 @@ Payload example: "file_name": "test.rb", "expires_at": null, "type": "ProjectSnippet", - "visibility_level": 0 + "visibility_level": 0, + "url": "http://example.com/gitlab-org/gitlab-test/-/snippets/53" } } ``` @@ -1109,6 +1110,9 @@ and later, the pipeline webhook returns only the latest jobs. In [GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89546) and later, pipeline webhooks triggered by blocked users are not processed. +In [GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123639) +and later, pipeline webhooks started to expose `object_attributes.name`. + Request header: ```plaintext @@ -1123,6 +1127,7 @@ Payload example: "object_attributes":{ "id": 31, "iid": 3, + "name": "Pipeline for branch: master", "ref": "master", "tag": false, "sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", @@ -1142,7 +1147,8 @@ Payload example: "key": "NESTOR_PROD_ENVIRONMENT", "value": "us-west-1" } - ] + ], + "url": "http://example.com/gitlab-org/gitlab-test/-/pipelines/31" }, "merge_request": { "id": 1, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 7fcb2680504..5c8fc5703dd 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -136,10 +136,25 @@ intermittently and are temporarily disabled. These webhooks are initially disabl for one minute, which is extended on each subsequent failure up to a maximum of 24 hours. Project or group webhooks that return response codes in the `4xx` range are understood to be -misconfigured and are permanently disabled until you manually re-enable -them yourself. +misconfigured and are permanently disabled until you [manually re-enable](#re-enable-disabled-webhooks) +the webhooks yourself. -For more information about disabled webhooks, see [troubleshooting](#troubleshooting). +### Re-enable disabled webhooks + +> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. + +If a webhook is failing, a banner displays at the top of the edit page explaining +why the webhook is disabled and when it is automatically re-enabled. For example: + +![A banner for a failing webhook, warning it has failed to connect and is retrying in 60 minutes](img/failed_banner.png) + +In the case of a failed webhook, an error banner is displayed: + +![A banner for a failed webhook, showing an error state, and explaining how to re-enable it](img/failed_banner_error.png) + +To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test +request succeeds, the webhook is re-enabled. ## Test a webhook @@ -274,6 +289,33 @@ Webhook requests to your endpoint include the following headers: | `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | +## Develop webhooks + +If you don't have an existing HTTPS endpoint or URL for your webhook setup, you must deploy one on a server. This HTTPS endpoint is used in configuration. To develop against GitLab webhooks and capture the payloads, you can use: + +- [Public webhook inspection and testing tools](#public-webhook-inspection-and-testing-tools) +- [The GitLab Development Kit (GDK)](#gitlab-development-kit-gdk) +- [Recently triggered webhook payloads in GitLab settings](#recently-triggered-webhook-payloads-in-gitlab-settings) + +### Public webhook inspection and testing tools + +You can use public tools to inspect and test webhook payloads. These tools act as catch-all endpoints for HTTP requests and respond with a `200 OK` HTTP status code. You can use these payloads to develop your webhook services. + +You should exercise caution when using these tools as you might be sending sensitive data to external tools. You should use test tokens with these tools and rotate any secrets inadvertently sent to a third party. + +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 + +### GitLab Development Kit (GDK) + +For a safer development environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit) to develop against GitLab webhooks locally. With the GDK, you can send webhooks from your local GitLab instance to a webhook receiver running locally on your machine. To use this approach, you must install and configure the GDK. + +### Recently triggered webhook payloads in GitLab settings + +You can [review recently triggered webhook payloads](#troubleshooting) in GitLab settings. For each webhook event, a detail page exists with information about the data GitLab sends and receives from the webhook endpoint. + ## Troubleshooting > **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3. @@ -334,19 +376,4 @@ 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). -### Re-enable disabled webhooks - -> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. - -If a webhook is failing, a banner displays at the top of the edit page explaining -why it is disabled, and when it is automatically re-enabled. For example: - -![A banner for a failing webhook, warning it has failed to connect and is retrying in 60 minutes](img/failed_banner.png) - -In the case of a failed webhook, an error banner is displayed: - -![A banner for a failed webhook, showing an error state, and explaining how to re-enable it](img/failed_banner_error.png) - -To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test -request succeeds, the webhook is re-enabled. +If a webhook is not triggered, the webhook might be [automatically disabled](#failing-webhooks). diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index ee5ca8eca78..8845aa8fdfd 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,15 +14,16 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. 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. The URL must contain `:id`. GitLab replaces `:id` with the issue number. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After you configure and enable YouTrack, a link appears on the GitLab project pages. This link takes you to the appropriate YouTrack project. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 19f6a3e315c..b14b9eac9da 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -52,7 +52,7 @@ Complete these steps in GitLab: ![ZenTao settings page](img/zentao_product_id.png) -1. To verify the ZenTao connection is working, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. <!--- end_remove --> diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 79278d1b3ad..7e5f26d3526 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -15,36 +15,36 @@ keep security vulnerabilities private or prevent surprises from leaking out. You can make an issue confidential when you create or edit an issue. +### In a new issue + When you create a new issue, a checkbox right below the text area is available to mark the issue as confidential. Check that box and select **Create issue** -to create the issue. For existing issues, edit them, check the -confidential checkbox and select **Save changes**. +to create the issue. When you create a confidential issue in a project, the project becomes listed in the **Contributed projects** section in your [profile](../../profile/index.md). **Contributed projects** does not show information about the confidential issue; it only shows the project name. -![Creating a new confidential issue](img/confidential_issues_create_v15_4.png) - -## Modify issue confidentiality +To create a confidential issue: -There are two ways to change an issue's confidentiality. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**). +1. From the dropdown list, select **New issue**. +1. Complete the [fields](create_issues.md#fields-in-the-new-issue-form). + - Select the **This issue is confidential...** checkbox. +1. Select **Create issue**. -The first way is to edit the issue and toggle the confidentiality checkbox. -After you save the issue, the confidentiality of the issue is updated. +### In an existing issue -The second way is to locate the **Confidentiality** section in the sidebar and select -**Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. +To change the confidentiality of an existing issue: -| Turn off confidentiality | Turn on confidentiality | -| :-----------: | :----------: | -| ![Turn off confidentiality](img/turn_off_confidentiality_v15_1.png) | ![Turn on confidentiality](img/turn_on_confidentiality_v15_1.png) | - -Every change from regular to confidential and vice versa, is indicated by a -system note in the issue's comments: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. +1. Select the title of your issue to view it. +1. On the right sidebar, next to **Confidentiality**, select **Edit**. +1. Select **Turn on** (or **Turn off** to make the issue non-confidential). -![Confidential issues system notes](img/confidential_issues_system_notes_v15_4.png) +Alternatively, you can use the `/confidential` [quick action](../quick_actions.md#issues-merge-requests-and-epics). -- **{eye-slash}** The issue is made confidential. -- **{eye}** The issue is made public. +## Who can see confidential issues When an issue is made confidential, only users with at least the Reporter role for the project have access to the issue. @@ -53,8 +53,8 @@ the issue even if they were actively participating before the change. ## Confidential issue indicators -There are a few things that visually separate a confidential issue from a -regular one. In the issues index page view, you can see the confidential (**{eye-slash}**) icon +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: ![Confidential issues index page](img/confidential_issues_index_page.png) @@ -62,8 +62,6 @@ next to the issues that are marked as confidential: If you don't have [enough permissions](#permissions-and-access-to-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. @@ -76,6 +74,14 @@ There is also an indicator on the sidebar denoting confidentiality. | :-----------: | :----------: | | ![Sidebar confidential issue](img/sidebar_confidential_issue.png) | ![Sidebar not confidential issue](img/sidebar_not_confidential_issue.png) | +Every change from regular to confidential and vice versa, is indicated by a +system note in the issue's comments: + +- **{eye-slash}** The issue is made confidential. +- **{eye}** The issue is made public. + +![Confidential issues system notes](img/confidential_issues_system_notes_v15_4.png) + ## 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. @@ -83,7 +89,7 @@ Learn how to create [merge requests for confidential issues](../merge_requests/c ## Permissions and access to confidential issues -There are two kinds of level access for confidential issues. The general rule +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**. diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 4511c89b0ff..3e7cfc12da7 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -28,11 +28,11 @@ Prerequisites: To create an issue: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Either: - - On the left sidebar, select **Issues**, and then, in the upper-right corner, select **New issue**. - - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, + - On the left sidebar, select **Plan > Issues**, and then, in the upper-right corner, select **New issue**. + - On the left sidebar, at the top, select the plus sign (**{plus}**) and then, under **In this project**, select **New issue**. 1. Complete the [fields](#fields-in-the-new-issue-form). @@ -51,8 +51,8 @@ Prerequisites: To create an issue from a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Issues**. 1. In the upper-right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. @@ -98,7 +98,7 @@ Prerequisites: To create an issue from a project issue board: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Issues > Boards**. 1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. @@ -106,7 +106,7 @@ To create an issue from a project issue board: To create an issue from a group issue board: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Issues > Boards**. 1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. @@ -130,8 +130,8 @@ Prerequisites: To email an issue to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. Select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. At the bottom of the page, select **Email a new issue to this project**. 1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). 1. From your email client, send an email to this address. @@ -197,7 +197,7 @@ To offer email support, enable [Service Desk](../service_desk.md) for your proje Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there. -### Fields in the new issue form +## Fields in the new issue form > - Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. > - Iteration field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233517) in GitLab 15.6. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 10b29feb072..9c04a40cb32 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -70,7 +70,7 @@ Support for PDF files is tracked in [issue 32811](https://gitlab.com/gitlab-org/ - [A project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429). - [An issue is deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427). - In GitLab 12.7 and later, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) - by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). + and in GitLab 16.1 and later it can be [verified by Geo as well](https://gitlab.com/gitlab-org/gitlab/-/issues/355660). ## View a design @@ -119,9 +119,7 @@ To move around the image while zoomed in, drag the image. ## Add a design to an issue -> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. -> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. -> - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. +> Ability to edit the description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1. Prerequisites: @@ -199,6 +197,21 @@ Only the latest version of the designs can be archived. Archived designs are not permanently lost. You can browse [previous versions](#add-a-new-version-of-a-design). +<!-- When content_editor_on_issues flag is removed, move version notes + to "Add a design to an issue", update that topic, and delete the one below. --> + +## Markdown and rich text editors for descriptions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +When this feature is enabled, you can use the Markdown and rich text editor in design descriptions. +It's the same editor you use for comments across GitLab. + ## Reorder designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. diff --git a/doc/user/project/issues/img/confidential_issues_create_v15_4.png b/doc/user/project/issues/img/confidential_issues_create_v15_4.png Binary files differdeleted file mode 100644 index ff489ad8605..00000000000 --- a/doc/user/project/issues/img/confidential_issues_create_v15_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png b/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png Binary files differdeleted file mode 100644 index e6050aec0de..00000000000 --- a/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png b/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png Binary files differdeleted file mode 100644 index c81ac85ab13..00000000000 --- a/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 6c9a645d817..a43dd65ed74 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -22,6 +22,13 @@ For more information about using issues, see the GitLab blog post: Issues are always associated with a specific project. If you have multiple projects in a group, you can view all of the projects' issues at once. +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=tTE6omrBBZI">Issues - Setting up your Organization with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/tTE6omrBBZI" frameborder="0" allowfullscreen> </iframe> +</figure> + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> To learn how the GitLab Strategic Marketing department uses GitLab issues with [labels](../labels.md) and [issue boards](../issue_board.md), see the video on diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 276cc3bc7a5..6f1c14b2b80 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -18,6 +18,8 @@ Prerequisites: To edit an issue: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select the title of your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the available fields. 1. Select **Save changes**. @@ -52,8 +54,8 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. 1. From the sidebar, edit the available fields. @@ -85,8 +87,8 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. 1. From the sidebar, edit the available fields. @@ -114,7 +116,8 @@ Prerequisites: To move an issue: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, select **Move issue**. 1. Search for a project to move the issue to. 1. Select **Move**. @@ -125,7 +128,7 @@ To move an issue: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15991) in GitLab 15.6. -You can move multiple issues at the same time when you’re in a project. +You can move multiple issues at the same time when you're in a project. You can't move tasks or test cases. Prerequisite: @@ -134,8 +137,8 @@ Prerequisite: To move multiple issues at the same time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to move. 1. From the right sidebar, select **Move selected**. @@ -204,10 +207,13 @@ Prerequisites: - You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. -To close an issue, you can do the following: +To close an issue, you can either: -- At the top of the issue, select **Close issue**. - In an [issue board](../issue_board.md), drag an issue card from its list into the **Closed** list. +- From any other page in the GitLab UI: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Plan > Issues**, then select your issue to view it. + 1. At the top of the issue, select **Close issue**. <!-- Delete when the `moved_mr_sidebar` feature flag is removed --> If you don't see this action at the top of an issue, your project or instance might have @@ -300,8 +306,8 @@ Prerequisites: To disable automatic issue closing: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Branch defaults**. 1. Clear the **Auto-close referenced issues on default branch** checkbox. 1. Select **Save changes**. @@ -330,6 +336,8 @@ Prerequisites: To change issue type: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the issue and select an issue type from the **Issue type** dropdown list: @@ -348,12 +356,16 @@ Prerequisites: To delete an issue: -1. In an issue, select **Issue actions** (**{ellipsis_v}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Delete issue**. Alternatively: -1. In an issue, select **Edit title and description** (**{pencil}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select the title of your issue to view it. +1. Select **Edit title and description** (**{pencil}**). 1. Select **Delete issue**. ## Promote an issue to an epic **(PREMIUM)** @@ -366,7 +378,9 @@ You can promote an issue to an [epic](../../group/epics/index.md) in the immedia To promote an issue to an epic: -1. In an issue, select **Issue actions** (**{ellipsis_v}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Promote to epic**. Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). @@ -387,7 +401,8 @@ You can use the `/promote_to_incident` [quick action](../quick_actions.md) to pr To add an issue to an [iteration](../../group/iterations/index.md): -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Iteration** section, select **Edit**. 1. From the dropdown list, select the iteration to associate this issue with. 1. Select any area outside the dropdown list. @@ -398,13 +413,13 @@ Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#i To view all issues assigned to you: -1. On the top bar, put your cursor in the **Search** box. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). 1. From the dropdown list, select **Issues assigned to me**. Or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>. -- On the top bar, in the upper-right corner, select **Issues** (**{issues}**). +- On the left sidebar, at the top, select **Issues** (**{issues}**). ## Filter the list of issues @@ -417,6 +432,8 @@ Or: To filter the list of issues: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. Above the list of issues, select **Search or filter results...**. 1. In the dropdown list that appears, select the attribute you want to filter by. 1. Select or type the operator to use for filtering the attribute. The following operators are @@ -456,8 +473,8 @@ when you [filter the list of issues](#filter-the-list-of-issues) by: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > List**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. ![filter issues by specific ID](img/issue_search_by_id_v15_0.png) @@ -469,7 +486,8 @@ To refer to an issue elsewhere in GitLab, you can use its full URL or a short re To copy the issue reference to your clipboard: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**). You can now paste the reference into another description or comment. @@ -492,7 +510,8 @@ For more information about creating comments by sending an email and the necessa To copy the issue's email address: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). ## Assignee @@ -508,7 +527,8 @@ themselves or another project member assigns them. To change the assignee on an issue: -1. Go to your issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Assignee** section, select **Edit**. 1. From the dropdown list, select the user to add as an assignee. 1. Select any area outside the dropdown list. @@ -548,7 +568,8 @@ Prerequisites: To edit health status of an issue: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Health status** section, select **Edit**. 1. From the dropdown list, select the status to add to this issue: @@ -556,7 +577,7 @@ To edit health status of an issue: - Needs attention (amber) - At risk (red) -You can see the issue’s health status in: +You can see the issue's health status in: - Issues list - Epic tree diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 2af15e06b98..7f98b62cabf 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -69,8 +69,8 @@ You can also assign and unassign labels with [quick actions](quick_actions.md): To view the **project's labels**: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. Or: @@ -86,8 +86,8 @@ project or group path where it was created. To view the **group's labels**: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. Or: @@ -108,8 +108,8 @@ Prerequisites: To create a project label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). @@ -142,8 +142,8 @@ To do so: To create a group label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). @@ -182,16 +182,16 @@ Prerequisites: To edit a **project** label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). ### Edit a group label To edit a **group** label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). ## Delete a label @@ -208,8 +208,8 @@ Prerequisites: To delete a **project** label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Either: - Next to the **Subscribe** button, select (**{ellipsis_v}**). @@ -221,8 +221,8 @@ To delete a **project** label: To delete a **group** label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. 1. Either: - Next to the **Subscribe** button, select (**{ellipsis_v}**). @@ -251,8 +251,8 @@ Prerequisites: To promote a project label to a group label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. @@ -302,8 +302,8 @@ Prerequisites: To add the default labels to the project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Select **Generate a default set of labels**. The following labels are created: @@ -441,8 +441,8 @@ Prerequisites: To prioritize a label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Next to a label you want to prioritize, select the star (**{star-o}**). ![Labels prioritized](img/labels_prioritized_v13_5.png) diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8b2cacf084e..7a1d9d6e6e3 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -118,8 +118,8 @@ Prerequisite: To add a user to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Invite members**. 1. If the user: @@ -176,8 +176,8 @@ Prerequisites: To add a group to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Invite a group**. 1. Select a group. 1. Select the highest [role](../../permissions.md) for users in the group. @@ -207,8 +207,8 @@ If the importing member's role in the target project is: To import users: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. @@ -232,8 +232,8 @@ Prerequisites: To remove a member from a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Next to the project member you want to remove, select **Remove member**. 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. @@ -269,8 +269,8 @@ You can filter and sort members in a project. ### Display inherited members -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. @@ -278,8 +278,8 @@ You can filter and sort members in a project. ### Display direct members -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press <kbd>Enter</kbd>. @@ -301,8 +301,8 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. On the top bar, select **Main menu > Projects** and find the project you want to be a member of. -1. By the project name, select **Request Access**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to be a member of. +1. By the project's name, select **Request Access**. ![Request access button](img/request_access_button.png) @@ -325,8 +325,8 @@ Prerequisite: - You must be the project owner. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. 1. Select **Save changes**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 452363c3d9a..aadc27fb2d3 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -57,16 +57,21 @@ You can share a project with a group by inviting that group to the project. To invite a group to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Invite a group**. 1. **Select a group** you want to add to the project. 1. **Select a role** you want to assign to the group. 1. Optional. Select an **Access expiration date**. 1. Select **Invite**. -All group members, members of subgroups, and members of other projects the group has access to -are given access to the project. In addition: +The following members are given access to the project: + +- All direct group members. +- Inherited group members. +- Members of other groups that have access to the group being invited (by [group share](../../group/manage.md#share-a-group-with-another-group)) + +In addition: - On the group's page, the project is listed on the **Shared projects** tab. - On the project's **Members** page, the group is listed on the **Groups** tab. @@ -93,8 +98,8 @@ For example, if a group member has the role of Developer, and the group is invit To view the maximum role assigned to a member: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. In the **Max role** column, view the user's maximum assigned role. ## View a group's shared projects @@ -103,7 +108,7 @@ In a group, a shared project is a project to which the group members gained acce To view a group's shared projects: -1. On the top bar, select **Main menu > Group** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. On the group page, select the **Shared projects** tab. A list of shared projects is displayed. diff --git a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_16_0.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_16_0.png Binary files differnew file mode 100644 index 00000000000..727dac0916b --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_16_0.png diff --git a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png Binary files differdeleted file mode 100644 index 306bf57354d..00000000000 --- a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png +++ /dev/null diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 717358df9f3..68d5665139a 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -67,7 +67,7 @@ if a user approves a merge request and is shown in the reviewer list, a green ch After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, -such as merge conflicts, [unresolved threads](../../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved), +such as merge conflicts, [unresolved threads](../index.md#prevent-merge-unless-all-threads-are-resolved), or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). To prevent merge request authors from approving their own merge requests, @@ -109,11 +109,11 @@ Without the approvals, the work cannot merge. Required approvals enable multiple > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default. +> - [Enabled by default on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/405023) in GitLab 16.1. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, -ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. -On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Whenever an approval rule cannot be satisfied, the rule is displayed as **(!) Auto approved**. This applies to the following conditions: diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index d55ca5dff04..bc5d4353ffc 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -104,7 +104,7 @@ supports multiple default rules: When an [eligible approver](#eligible-approvers) approves a merge request, it reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: -![Approvals premium merge request widget](img/approvals_premium_mr_widget_v13_3.png) +![Approvals premium merge request widget](img/approvals_premium_mr_widget_16_0.png) <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Multiple Approvers](https://www.youtube.com/watch?v=8JQJ5821FrA). @@ -186,8 +186,8 @@ oversight on proposed work. To enable approval permissions for these users witho granting them push access: 1. [Create a protected branch](../../protected_branches.md) -1. [Create a new group](../../../group/manage.md#create-a-group). -1. [Add the user to the group](../../../group/manage.md#add-users-to-a-group), +1. [Create a new group](../../../group/index.md#create-a-group). +1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group), based on the Reporter role. @@ -195,7 +195,7 @@ granting them push access: 1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: - For a new rule, select **Add approval rule** and target the protected branch. - For an existing rule, select **Edit** and target the protected branch. -1. [Add the group](../../../group/manage.md#create-a-group) to the permission list. +1. [Add the group](../../../group/index.md#create-a-group) to the permission list. ![Update approval rule](img/update_approval_rule_v13_10.png) @@ -217,6 +217,14 @@ on a merge request, you can either add or remove approvers: Administrators can change the [merge request approvals settings](settings.md#prevent-editing-approval-rules-in-merge-requests) to prevent users from overriding approval rules for merge requests. +## Require multiple approvals for a rule + +To create an approval rule which requires more than one approval: + +- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `2` or more. +- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) + to set the `approvals_required` attribute to `2` or more. + ## Configure optional approval rules Merge request approvals can be optional for projects where approvals are diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 8f6b1a32424..94f506ba556 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -27,23 +27,17 @@ To view the diff of changes included in a merge request: 1. Select the file you want to view. 1. To hide the file browser, select **Show file browser** again. -In [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) and later, files -with many changes are collapsed to improve performance. GitLab displays the message: +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**. ## Show one file at a time -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. - For larger merge requests, you can review one file at a time. You can change this setting [temporarily in a merge request](#in-a-merge-request-show-only-one-file-at-a-time), or so it [applies to all merge requests](#in-all-merge-requests-show-only-one-file-at-a-time). ### In a merge request, show only one file at a time -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) in GitLab 13.7. - To temporarily change your viewing preferences for a specific merge request: 1. Go to your merge request, and below the merge request title, select **Changes**. @@ -149,3 +143,31 @@ When there are conflicts between the source and target branch, we show an alert per conflicted file on the merge request diff: ![Example of a conflict alert shown in a merge request diff](img/conflict_ui_v15_6.png) + +## Add a comment to a merge request file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121429) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `comment_on_files`. +On GitLab.com, this feature is not available. + +You can add comments to a merge request diff file. These comments persist across +rebases and file changes. + +To add a comment to a merge request file: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Select **Changes**. +1. In the header for the file you want to comment on, select **Comment** (**{comment}**). + +## Add a comment to an image + +In merge requests and commit detail views, you can add a comment to an image. +This comment can also be a thread. + +1. Hover your mouse over the image. +1. Select the location where you want to comment. + +An icon is displayed on the image and a comment field is displayed. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 004d24778b7..6669b2883a4 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -52,8 +52,8 @@ Commit `G` is added after the cherry-pick. After a merge request is merged, you can cherry-pick all changes introduced by the merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**, and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. 1. In the upper-right corner, select **Cherry-pick**: @@ -70,8 +70,8 @@ You can cherry-pick a single commit from multiple locations in your GitLab proje To cherry-pick a commit from the list of all commits for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Commits**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Commits**. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. @@ -84,8 +84,8 @@ You can cherry-pick commits from any merge request in your project, regardless o whether the merge request is open or closed. To cherry-pick a commit from the list of commits included in a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**, and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. @@ -98,8 +98,8 @@ list of commits included in a merge request: You can cherry-pick from the list of previous commits affecting an individual file when you view that file in your project's Git repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files** and go to the file +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository** and go to the file changed by the commit. 1. Select **History**, then select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index f8c24e4067b..c930c5c6f7f 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -29,8 +29,8 @@ Prerequisite: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Depending on the type of template you want to create, scroll to either [**Merge commit message template**](#default-template-for-merge-commits) or [**Squash commit message template**](#default-template-for-squash-commits). @@ -71,6 +71,7 @@ GitLab creates a squash commit message with this template: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) `reviewed_by` variable in GitLab 15.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) `local_reference` variable in GitLab 16.1. Commit message templates support these variables: @@ -82,6 +83,7 @@ Commit message templates support these variables: | `%{issues}` | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` | | `%{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` | | `%{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 cc6ecd8398f..a36e45d159a 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -14,46 +14,72 @@ These commits are displayed on the merge request's **Commits** tab. From this tab, you can review commit messages and copy a commit's SHA when you need to [cherry-pick changes](cherry_pick_changes.md). -## Navigate merge request commits +## View commits in a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. +To see the commits included in a merge request: -To navigate commits in a merge request: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, then select your merge request. +1. To show a list of the commits in the merge request, newest first, select **Commits** . + To read more about the commit, select **Toggle commit description** (**{ellipsis_h}**) + on any commit. +1. To view the changes in the commit, select the title of the commit link. +1. To view other commits in the merge request, either: -1. Select the **Commits** tab. -1. Select the commit link. The most recent commit is displayed. -1. Navigate through the commits by either: + - Select **Prev** or **Next**. + - Use keyboard shortcuts: <kbd>X</kbd> (previous commit) and <kbd>C</kbd> (next commit). - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. +If your merge request builds upon a previous merge request, you might +need to [include more commits for context](#show-commits-from-previous-merge-requests). -![Merge requests commit navigation](img/commit_nav_v16_0.png) +### Show commits from previous merge requests -## View merge request commits in context - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. -When reviewing a merge request, it helps to have more context about the changes -made. That includes unchanged lines in unchanged files, and previous commits -that have already merged that the change is built on. +When you review a merge request, you might need information from previous commits +to help understand the commits you're reviewing. You might need more context +if another merge request: + +- Changed files your current merge request doesn't modify, so those files aren't shown + in your current merge request's diff. +- Changed files that you're modifying in your current merge request, and you need + to see the progression of work. To add previously merged commits to a merge request for more context: -1. Go to your merge request. -1. Select the **Commits** tab. -1. Scroll to the end of the list of commits, and select **Add previously merged commits**: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, then select your merge request. +1. Select **Commits**. +1. Scroll to the end of the list of commits, and select **Add previously merged commits**. 1. Select the commits that you want to add. 1. Select **Save changes**. +## Add a comment to a commit + +WARNING: +Threads created this way are lost if the commit ID changes after a +force push. + +To add discussion to a specific commit: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Commits**. +1. Below the commits, in the **Comment** field, enter a comment. +1. Save your comment as either a standalone comment, or a thread: + - To add a comment, select **Comment**. + - To start a thread, select the down arrow (**{chevron-down}**), then select **Start thread**. + ## View diffs between commits To view the changes between previously merged commits: -1. On your merge request, select the **Changes** tab. -1. By **Compare**, select the commit you want to view: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, then select your merge request. +1. Select **Changes**. +1. By **Compare** (**{file-tree}**), select the commits to compare: ![Previously merged commits](img/previously_merged_commits_v16_0.png) -If you selected to add previously merged commits, they are displayed in the list. +If you selected to add previously merged commits for context, those commits are +also shown in the list. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index cc8f8cb2fe6..44cef4d63e5 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,8 +59,8 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find the merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. The conflicts are @@ -84,8 +84,8 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find the merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index a91d324016a..4eb4476422f 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,8 +19,8 @@ to streamline merge request creation. You can create a merge request from the list of merge requests. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. In the upper-right corner, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. @@ -95,8 +95,8 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Type a branch name and select **New branch**. 1. Above the file list, on the right side, select **Create merge request**. A merge request is created. The default branch is the target. @@ -142,9 +142,9 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select your fork of the repository. -1. On the left menu, go to **Merge requests**, and select **New merge request**. +1. On the left sidebar, select **Code > Merge requests**, and select **New merge request**. 1. In the **Source branch** dropdown list box, select the branch in your forked repository as the source branch. 1. In the **Target branch** dropdown list box, select the branch from the upstream repository as the target branch. You can set a [default target project](#set-the-default-target-project) to @@ -171,8 +171,8 @@ Prerequisites: To create a merge request by sending an email: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. In the upper-right corner, select **Email a new merge request to this project**. An email address is displayed. Copy this address. Ensure you keep this address private. @@ -216,8 +216,8 @@ scenarios when you create a new merge request: To have merge requests from a fork by default target your own fork (instead of the upstream project), you can change the default. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Settings > General > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f40b82a6280..f8988ae7bd7 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -12,8 +12,8 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** . +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. 1. Select **Actions** (**{ellipsis_v}**) **> Export as CSV**. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 3d92fc9a91e..1cd81e2aac2 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -57,8 +57,8 @@ information about the dependency: To view dependency information on a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area. Dependent merge requests display information about the total number of dependencies set, such as **(status-warning)** **Depends on 1 merge request being merged**. @@ -105,8 +105,8 @@ Prerequisite: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. In **Merge request dependencies**, paste either the reference or the full URL to the merge requests that should merge before this work merges. References @@ -120,8 +120,8 @@ Prerequisite: - You must have a role in the project that allows you to edit merge requests. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. Scroll to **Merge request dependencies** and select **Remove** next to the reference for each dependency you want to remove. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 88e5e4a6283..6f309d2db24 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -12,7 +12,7 @@ or open threads, you can prevent it from being accepted before you [mark it as ready](#mark-merge-requests-as-ready). Flag it as a draft to disable the **Merge** button until you remove the **Draft** flag: -![Blocked Merge Button](img/draft_blocked_merge_button_v13_10.png) +![Blocked Merge Button](img/merge_request_draft_blocked_v16_0.png) ## Mark merge requests as drafts @@ -42,10 +42,7 @@ When a merge request is ready to be merged, you can remove the `Draft` flag in s - **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as ready**. Users with at least the Developer role - can also scroll to the bottom of the merge request description and select **Mark as ready**: - - ![Mark as ready](img/draft_blocked_merge_button_v13_10.png) - + can also scroll to the bottom of the merge request description and select **Mark as ready**. - **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` from the beginning of the title, or clear **Mark as draft** below the **Title** field. @@ -71,7 +68,7 @@ draft merge requests: 1. Select **Yes** to include drafts, or **No** to exclude, and press **Return** to update the list of merge requests: - ![Filter draft merge requests](img/filter_draft_merge_requests_v13_10.png) + ![Filter draft merge requests](img/filter_draft_merge_requests_v16_0.png) ## Pipelines for drafts diff --git a/doc/user/project/merge_requests/img/auto_merge_ready_v16_0.png b/doc/user/project/merge_requests/img/auto_merge_ready_v16_0.png Binary files differnew file mode 100644 index 00000000000..e68057e73a0 --- /dev/null +++ b/doc/user/project/merge_requests/img/auto_merge_ready_v16_0.png diff --git a/doc/user/project/merge_requests/img/commit_nav_v16_0.png b/doc/user/project/merge_requests/img/commit_nav_v16_0.png Binary files differdeleted file mode 100644 index 6005e516fff..00000000000 --- a/doc/user/project/merge_requests/img/commit_nav_v16_0.png +++ /dev/null diff --git a/doc/user/discussions/img/create_new_issue_v15_4.png b/doc/user/project/merge_requests/img/create_new_issue_v15_4.png Binary files differindex 3720b601cc5..3720b601cc5 100644 --- a/doc/user/discussions/img/create_new_issue_v15_4.png +++ b/doc/user/project/merge_requests/img/create_new_issue_v15_4.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png Binary files differdeleted file mode 100644 index 3bac9f7fee8..00000000000 --- a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png Binary files differdeleted file mode 100644 index 4458df987d6..00000000000 --- a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v16_0.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v16_0.png Binary files differnew file mode 100644 index 00000000000..f4356aade16 --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v16_0.png diff --git a/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png b/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png Binary files differdeleted file mode 100644 index 398820f7864..00000000000 --- a/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png b/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png Binary files differdeleted file mode 100644 index c35f2c8a58b..00000000000 --- a/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_assignees_v16_0.png b/doc/user/project/merge_requests/img/merge_request_assignees_v16_0.png Binary files differnew file mode 100644 index 00000000000..114ddf612e0 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_assignees_v16_0.png diff --git a/doc/user/project/merge_requests/img/merge_request_draft_blocked_v16_0.png b/doc/user/project/merge_requests/img/merge_request_draft_blocked_v16_0.png Binary files differnew file mode 100644 index 00000000000..88fe1ec34c0 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_draft_blocked_v16_0.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differdeleted file mode 100644 index ce1d6bab536..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_pipeline.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png Binary files differdeleted file mode 100644 index dde2680ed74..00000000000 --- a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/mwps_v15_4.png b/doc/user/project/merge_requests/img/mwps_v15_4.png Binary files differdeleted file mode 100644 index f042912d470..00000000000 --- a/doc/user/project/merge_requests/img/mwps_v15_4.png +++ /dev/null diff --git a/doc/user/discussions/img/new-issue-one-thread_v14_3.png b/doc/user/project/merge_requests/img/new-issue-one-thread_v14_3.png Binary files differindex 34d3a3be0a7..34d3a3be0a7 100644 --- a/doc/user/discussions/img/new-issue-one-thread_v14_3.png +++ b/doc/user/project/merge_requests/img/new-issue-one-thread_v14_3.png diff --git a/doc/user/project/merge_requests/img/post_merge_pipeline_v16_0.png b/doc/user/project/merge_requests/img/post_merge_pipeline_v16_0.png Binary files differnew file mode 100644 index 00000000000..b14ce645850 --- /dev/null +++ b/doc/user/project/merge_requests/img/post_merge_pipeline_v16_0.png diff --git a/doc/user/discussions/img/unresolved_threads_v15_4.png b/doc/user/project/merge_requests/img/unresolved_threads_v15_4.png Binary files differindex 1d1669de0f1..1d1669de0f1 100644 --- a/doc/user/discussions/img/unresolved_threads_v15_4.png +++ b/doc/user/project/merge_requests/img/unresolved_threads_v15_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a65c5518658..38125f623eb 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -50,8 +50,8 @@ You can view merge requests for your project, group, or yourself. To view all merge requests for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. @@ -59,8 +59,8 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd> To view merge requests for all projects in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Code > Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -68,21 +68,17 @@ If your group contains subgroups, this view also displays merge requests from th To view all merge requests assigned to you: -<!-- vale gitlab.FirstPerson = NO --> - -1. On the top bar, put your cursor in the **Search** box. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). 1. From the dropdown list, select **Merge requests assigned to me**. -<!-- vale gitlab.FirstPerson = YES --> - or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. or: -1. On the top bar, in the upper-right corner, select **Merge requests** (**{merge-request-open}**). -1. From the dropdown list, select **Assigned to you**. +1. On the left sidebar, at the top, select **Merge requests** (**{merge-request}**). +1. From the dropdown list, select **Assigned**. ## Filter the list of merge requests @@ -93,6 +89,8 @@ or: To filter the list of merge requests: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Above the list of merge requests, select **Search or filter results...**. 1. From the dropdown list, select the attribute you wish to filter by. Some examples: - [**By environment or deployment date**](#by-environment-or-deployment-date). @@ -132,17 +130,15 @@ Projects using a [fast-forward merge method](methods/index.md#fast-forward-merge do not return results, as this method does not create a merge commit. When filtering by an environment, a dropdown list presents all environments that -you can choose from: +you can choose from. -![Filter MRs by their environment](img/filtering_merge_requests_by_environment_v14_6.png) +When filtering by `Deployed-before` or `Deployed-after`: -When filtering by `Deployed-before` or `Deployed-after`, the date refers to when -the deployment to an environment (triggered by the merge commit) completed successfully. -You must enter the deploy date manually. Deploy dates -use the format `YYYY-MM-DD`, and must be quoted if you wish to specify -both a date and time (`"YYYY-MM-DD HH:MM"`): - -![Filter MRs by a deploy date](img/filtering_merge_requests_by_date_v14_6.png) +- The date refers to when the deployment to an environment (triggered by the + merge commit) completed successfully. +- You must enter the deploy date manually. +- Deploy dates use the format `YYYY-MM-DD`, and must be wrapped in double quotes (`"`) + if you want to specify both a date and time (`"YYYY-MM-DD HH:MM"`). ## Add changes to a merge request @@ -167,8 +163,8 @@ To assign the merge request to a user, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in a merge request, or: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. 1. Search for the user you want to assign, and select the user. @@ -182,13 +178,13 @@ The merge request is added to the user's assigned merge request list. GitLab enables multiple assignees for merge requests, if multiple people are accountable for it: -![multiple assignees for merge requests sidebar](img/multiple_assignees_for_merge_requests_sidebar.png) +![multiple assignees for merge requests sidebar](img/merge_request_assignees_v16_0.png) To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want to assign the merge request to. @@ -300,7 +296,7 @@ For a software developer working in a team: 1. Your manager: 1. Pushes a commit with their final review. 1. [Approves the merge request](approvals/index.md). - 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). + 1. Sets it to [auto-merge](merge_when_pipeline_succeeds.md) (formerly **Merge when pipeline succeeds**). 1. Your changes get deployed to production with [manual jobs](../../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. @@ -316,18 +312,19 @@ For a web developer writing a webpage for your company's website: ## Filter activity in a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387070) in GitLab 16.0. Available to GitLab team members only. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `mr_activity_filters` for individual or groups of users. -On GitLab.com, this feature unavailable. +On GitLab.com, this feature is enabled for GitLab team members only. To understand the history of a merge request, filter its activity feed to show you only the items that are relevant to you. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Select a merge request. 1. Scroll to **Activity**. 1. On the right side of the page, select **Activity filter** to show the filter options. @@ -351,6 +348,78 @@ only the items that are relevant to you. Your selection persists across all merge requests. You can also change the sort order by clicking the sort button on the right. +## Resolve a thread + +> Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. + +In a merge request, you can resolve a thread when you want to finish a conversation. + +Prerequisites: + +- You must have at least the Developer role + or be the author of the change being reviewed. +- Resolvable threads can be added only to merge requests. It doesn't work + for comments in issues, commits, or snippets. + +To resolve a thread: + +1. Go to the thread. +1. Do one of the following: + - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**). + - Below the last reply, in the **Reply** field, select **Resolve thread**. + - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. + +At the top of the page, the number of unresolved threads is updated: + +![Count of unresolved threads](img/unresolved_threads_v15_4.png) + +### Move all unresolved threads in a merge request to an issue + +If you have multiple unresolved threads in a merge request, you can +create an issue to resolve them separately. In the merge request, at the top of the page, +select the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Resolve all with new issue**: + +![Open new issue for all unresolved threads](img/create_new_issue_v15_4.png) + +All threads are marked as resolved, and a link is added from the merge request to +the newly created issue. + +### Move one unresolved thread in a merge request to an issue + +If you have one specific unresolved thread in a merge request, you can +create an issue to resolve it separately. In the merge request, under the last reply +to the thread, next to **Resolve thread**, select **Create issue to resolve thread** (**{issue-new}**): + +![Create issue for thread](img/new-issue-one-thread_v14_3.png) + +The thread is marked as resolved, and a link is added from the merge request to +the newly created issue. + +### Prevent merge unless all threads are resolved + +You can prevent merge requests from being merged until all threads are +resolved. When this setting is enabled, the **Unresolved threads** counter in a merge request +is shown in orange when at least one thread remains unresolved. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. +1. In the **Merge checks** section, select the **All threads must be resolved** checkbox. +1. Select **Save changes**. + +### Automatically resolve threads in a merge request when they become outdated + +You can set merge requests to automatically resolve threads when lines are modified +with a new push. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. +1. In the **Merge options** section, select + **Automatically resolve merge request diff threads when they become outdated**. +1. Select **Save changes**. + +Threads are now resolved if a push makes a diff section outdated. +Threads on lines that don't change and top-level resolvable threads are not resolved. + ## Related topics - [Create a merge request](creating_merge_requests.md) 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 7588af70bd4..66c3b1fda74 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -9,29 +9,29 @@ type: reference, concepts > **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. -NOTE: -[In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** become **Set to auto-merge**. - If you review a merge request and it's ready to merge, but the pipeline hasn't -completed yet, you can set it to merge when the pipeline succeeds (MWPS). You don't +completed yet, you can set it to auto-merge. You don't have to remember later to merge the work manually: -![Enable MWPS on a merge request](img/mwps_v15_4.png) +![Auto-merge is ready](img/auto_merge_ready_v16_0.png) + +NOTE: +[In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** are renamed **Set to auto-merge**. If the pipeline succeeds, the merge request is merged. If the pipeline fails, the author can either retry any failed jobs, or push new commits to fix the failure: - If a retried job succeeds on the second try, the merge request is merged. -- If new commits are added to the merge request, GitLab cancels the MWPS request +- If new commits are added to the merge request, GitLab cancels the request to ensure the new changes are reviewed before merge. -## Set a merge request to MWPS +## Auto-merge a merge request Prerequisites: - You must have at least the Developer role in the project. - If the project is configured to require it, all threads in the - merge request [must be resolved](../../discussions/index.md#resolve-a-thread). + merge request [must be resolved](index.md#resolve-a-thread). - The merge request must have received all required approvals. To do this when pushing from the command line, use the `merge_request.merge_when_pipeline_succeeds` @@ -39,20 +39,20 @@ To do this when pushing from the command line, use the `merge_request.merge_when To do this from the GitLab user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 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**. -1. Select **Merge when pipeline succeeds**. +1. Select **Auto-merge**. -If a new comment is added to the merge request after you select **Merge when pipeline succeeds**, +If a new comment is added to the merge request after you select **Auto-merge**, but before the pipeline completes, GitLab blocks the merge until you resolve all existing threads. ## Cancel an auto-merge -If a merge request is set to MWPS, you can cancel it. +If a merge request is set to auto-merge, you can cancel it. Prerequisites: @@ -62,8 +62,8 @@ Prerequisites: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Scroll to the merge request reports section. 1. Select **Cancel auto-merge**. @@ -88,8 +88,8 @@ Prerequisites: To enable this setting: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Scroll to **Merge checks**, and select **Pipelines must succeed**. This setting also prevents merge requests from being merged if there is no pipeline, which can [conflict with some rules](#merge-requests-dont-merge-when-successful-pipeline-is-required). @@ -109,9 +109,8 @@ Prerequisite: To change this behavior: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Under **Merge checks**: - Select **Pipelines must succeed**. - Select **Skipped pipelines are considered successful**. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 02bd4ed0502..7bb10303d7e 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -26,8 +26,8 @@ gitGraph ## Configure a project's merge method -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Select your desired **Merge method** from these options: - Merge commit - Merge commit with semi-linear history diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 77fd78ee0d0..c4288a7793c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -30,8 +30,8 @@ Prerequisites: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area, and find the report showing when the merge request was merged. 1. Select **Revert**. @@ -55,13 +55,13 @@ Prerequisites: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. If you know the merge request that contains the commit: - 1. On the left sidebar, select **Merge requests** and identify your merge request. + 1. Select **Code > Merge requests**, then identify and select your merge request. 1. Select **Commits**, then select the title of the commit you want to revert. This displays the commit in the **Changes** tab of your merge request. 1. Select the commit hash you want to revert. GitLab displays the contents of the commit. 1. If you don't know the merge request the commit originated from: - 1. On the left sidebar, select **Repository > Commits**. + 1. Select **Code > Commits**. 1. Select the title of the commit to display full information about the commit. 1. In the upper-right corner, select **Options**, then select **Revert**. 1. In **Revert in branch**, select the branch to revert your changes into. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 0de38874304..86468af06a2 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -7,9 +7,6 @@ type: index, reference # Merge request reviews **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. - [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) to propose changes. Your team leaves [comments](../../../discussions/index.md) on @@ -26,7 +23,7 @@ For an overview, see [Merge request review](https://www.youtube.com/watch?v=2May ## Suggested reviewers **(ULTIMATE SAAS)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/alpha-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/experiment-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6. > - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10. @@ -52,9 +49,6 @@ of a merge request with new commits. ## Review a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) from GitLab Premium to GitLab Free in 13.1. - When you review a merge request, you can create comments that are visible only to you. When you're ready, you can publish them together in a single action. To start your review: @@ -62,7 +56,7 @@ To start your review: 1. Go to the merge request you want to review, and select the **Changes** tab. For more information about navigating the diffs displayed in this tab, see [Changes in merge requests](../changes.md). -1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines +1. Select **Add a comment to this line** (**{comment}**) in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can [select multiple lines](#comment-on-multiple-lines). 1. In the text area, write your first comment, then select **Start a review** below your comment. @@ -75,8 +69,7 @@ To start your review: are now visible, and any [quick actions](../../quick_actions.md) included in your comments are performed. -[In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), -if you [approve a merge request](../approvals/index.md#approve-a-merge-request) and +If you [approve a merge request](../approvals/index.md#approve-a-merge-request) and are shown in the reviewer list, a green check mark **{check-circle-filled}** displays next to your name. @@ -84,8 +77,8 @@ displays next to your name. To download the changes included in a merge request as a diff: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Plain diff**. @@ -107,8 +100,8 @@ curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git a To download the changes included in a merge request as a patch file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Patches**. @@ -147,7 +140,7 @@ When you submit your review, GitLab: ### Resolve or unresolve thread with a comment -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread). +Review comments can also resolve or unresolve [resolvable threads](../index.md#resolve-a-thread). To resolve or unresolve a thread when replying to a comment: 1. In the comment text area, write your comment. @@ -161,8 +154,6 @@ Pending comments display information about the action to be taken when the comme ### Add a new comment -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. - If you have a review in progress, you can also add a comment from the **Overview** tab by selecting **Add to review**: @@ -170,9 +161,6 @@ If you have a review in progress, you can also add a comment from the **Overview ### Approval Rule information for Reviewers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - [Feature flag `reviewer_approval_rules` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. - When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) below the name of each suggested reviewer. [Code Owners](../../codeowners/index.md) are displayed as `Codeowner` without group detail. @@ -187,8 +175,6 @@ This example shows reviewers and approval rules in a merge request sidebar: ### Request a new review -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. - After a reviewer completes their [merge request reviews](../../../discussions/index.md), the author of the merge request can request a new review from the reviewer: @@ -202,18 +188,14 @@ them a notification email. ## Comment on multiple lines -> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) select-and-drag features in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. - When commenting on a diff, you can select which lines of code your comment refers to by either: ![Comment on any diff file line](img/comment-on-any-diff-line_v13_10.png) -- Dragging the **{comment}** **comment** icon in the gutter to highlight +- Dragging **Add a comment to this line** (**{comment}**) in the gutter to highlight lines in the diff. GitLab expands the diff lines and displays a comment box. -- After starting a comment by selecting the **{comment}** **comment** icon in the +- After starting a comment by selecting **Add a comment to this line** (**{comment}**) in the gutter, select the first line number your comment refers to in the **Commenting on lines** select box. New comments default to single-line comments, unless you select a different starting line. @@ -245,8 +227,6 @@ To update multiple project merge requests at the same time: ## Bulk edit merge requests at the group level **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in GitLab 12.2. - Users with at least the Developer role can manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: @@ -315,8 +295,6 @@ the command line. ### Copy the branch name for local checkout -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. - The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request. @@ -418,9 +396,6 @@ All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) ## Cached merge request count -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327319) in GitLab 14.0. - In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 9187c5fad44..24197c5c313 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -17,8 +17,8 @@ merge request, authored by the user who suggested the changes. ## Create suggestions -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. On the secondary menu, select **Changes**. 1. Find the lines of code you want to change. - To select a single line: @@ -80,8 +80,8 @@ Prerequisites: To apply suggested changes directly from the merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. Find the comment containing the suggestion you want to apply. - To apply suggestions individually, select **Apply suggestion**. - To apply multiple suggestions in a single commit, select **Add suggestion to batch**. @@ -128,8 +128,8 @@ Merge requests created from forks use the template defined in the target project To meet your project's needs, you can customize these messages and include other placeholder variables: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Scroll to **Merge suggestions**, and alter the text to meet your needs. See [Supported variables](#supported-variables) for a list of placeholders you can use in this message. @@ -155,7 +155,7 @@ For example, to customize the commit message to output ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. @@ -163,8 +163,8 @@ For example, to customize the commit message to output To reduce the number of commits added to your branch, you can apply multiple suggestions in a single commit. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. For each suggestion you want to apply, and select **Add suggestion to batch**. 1. Optional. To remove a suggestion, select **Remove from batch**. 1. After you add your desired suggestions, select **Apply suggestions**. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 075716e90c8..b9b8485021b 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -71,8 +71,8 @@ Prerequisites: To configure the default squashing behavior for all merge requests in your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. In the **Squash commits when merging** section, select your desired behavior: - **Do not allow**: Squashing is never performed, and the option is not displayed. - **Allow**: Squashing is allowed, but cleared by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 0e339c65ed5..a151a7cbf1b 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -36,8 +36,8 @@ see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869). By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Select the **Status checks must succeed** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index a7aa86a16d4..639552ca75a 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -41,11 +41,11 @@ for environments. If it's the first time the branch is deployed, the link returns a `404` error until done. During the deployment, the stop button is disabled. If the pipeline fails to deploy, the deployment information is hidden. -![Merge request pipeline](img/merge_request_pipeline.png) +![Merge request pipeline](img/post_merge_pipeline_v16_0.png) For more information, [read about pipelines](../../../ci/pipelines/index.md). -## Merge when pipeline succeeds (MWPS) +## Set auto-merge Set a merge request that looks ready to merge to [merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). @@ -65,7 +65,7 @@ faster to preview proposed modifications. ## License compliance **(ULTIMATE)** -If you have configured [License Compliance](../../compliance/license_compliance/index.md) for your project, then you can view a list of licenses that are detected for your project's dependencies. +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. ![Merge request pipeline](img/license_compliance_widget_v15_3.png) diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 4641af262ca..47325ee7c90 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -37,9 +37,8 @@ For information about project and group milestones API, see: To view the milestone list: -1. On the top bar, select **Main menu > Projects** and find your project or - **Main menu > Groups** and find your group. -1. Select **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. In a project, GitLab displays milestones that belong to the project. In a group, GitLab displays milestones that belong to the group and all projects in the group. @@ -67,7 +66,8 @@ You might not see some milestones because they're in projects or groups you're n To do so: -1. On the top bar select **Main menu > Your work**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. 1. On the left sidebar, select **Milestones**. ### View milestone details @@ -121,8 +121,8 @@ Prerequisites: To create a milestone: -1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. 1. Select **New milestone**. 1. Enter the title. 1. Optional. Enter description, start date, and due date. @@ -140,7 +140,8 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. 1. Select a milestone's title. 1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. 1. Edit the title, start date, due date, or description. @@ -156,7 +157,8 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. 1. Select a milestone's title. 1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. 1. Select **Delete milestone**. @@ -181,8 +183,8 @@ Prerequisites: To promote a project milestone: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Milestones**. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. - Select the milestone title, and then select **Milestone actions** (**{ellipsis_v}**) > **Promote**. diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index a2c2ab0cc40..81c4bc20301 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -12,7 +12,7 @@ To enable the feature, ask an administrator to [enable the feature flag](../../. On GitLab.com, this feature is in private testing only. NOTE: -Model experiment tracking is an [experimental feature](../../../../policy/alpha-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. +Model experiment tracking is an [experimental feature](../../../../policy/experiment-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. When creating machine learning models, data scientists often experiment with different parameters, configurations, and feature engineering to improve the performance of the model. Keeping track of all this metadata and the associated @@ -70,8 +70,8 @@ Prerequisites: To list the current active experiments, either go to `https/-/ml/experiments` or: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Packages & registries > Model experiments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Deploy > 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/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index a97fc1171fc..606f0474cb1 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 @@ -53,8 +53,8 @@ this document for an [overview on DNS records](dns_concepts.md). To add your custom domain to GitLab Pages: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -165,10 +165,10 @@ If you're using Cloudflare, check #### 4. Verify the domain's ownership -Once you have added all the DNS records: +After you have added all the DNS records: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -262,8 +262,8 @@ meet these requirements. - To add the certificate at the time you add a new domain: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > Pages**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -274,8 +274,8 @@ meet these requirements. - To add the certificate to a domain previously added: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > Pages**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -308,8 +308,8 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). 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 91633e01ad2..15152efb80c 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,8 +42,8 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -72,8 +72,8 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -90,8 +90,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). 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 17618146350..167c72fdc89 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,8 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select the project's name. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the **Add** (**{plus}**) dropdown list, select **New file**. 1. From the **Select a template type** dropdown list, select `.gitlab-ci.yml`. 1. From the **Apply a template** dropdown list, in the **Pages** section, select the name of your SSG. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 00635fe6db2..16d5cfcca4a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Incubation +stage: Plan +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 --- @@ -33,8 +33,8 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index a68ad604989..9b299b46f75 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -129,12 +129,14 @@ If you are running a self-managed instance of GitLab, ### Configure GitLab Pages in a Helm Chart (Kubernetes) instance To configure GitLab Pages on instances deployed via Helm chart (Kubernetes), use either: - -- [The `gitlab-pages` subchart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-pages/). -- [An external GitLab Pages instance](https://docs.gitlab.com/charts/advanced/external-gitlab-pages/). + +- [The `gitlab-pages` subchart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-pages/). +- [An external GitLab Pages instance](https://docs.gitlab.com/charts/advanced/external-gitlab-pages/). ## Security for GitLab Pages +### Namespaces that contain `.` + If your username is `example`, your GitLab Pages website is located at `example.gitlab.io`. GitLab allows usernames to contain a `.`, so a user named `bar.example` could create a GitLab Pages website `bar.example.gitlab.io` that effectively is a subdomain of your @@ -153,3 +155,9 @@ document.cookie = "key=value;domain=example.gitlab.io"; This issue doesn't affect users with a custom domain, or users who don't set any cookies manually with JavaScript. + +### Shared cookies + +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. + +To ensure each project uses different cookies, enable the Pages [unique domains](introduction.md#enable-unique-domains) feature for your project. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 05d0b461fea..73bfe018a7d 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -66,8 +66,8 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](index.md#menu-position-test). @@ -94,6 +94,25 @@ the group must be at the top level and not a subgroup. For [project websites](../../project/pages/getting_started_part_one.md#project-website-examples), you can create your project first and access it under `http(s)://namespace.example.io/projectname`. +## Enable unique domains + +> - [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 on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `pages_unique_domain`. +On GitLab.com, by default this feature is available. + +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. + +To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. +1. Select the **Use unique domain** checkbox. +1. Select **Save changes**. + ## Specific configuration options for Pages Learn how to set up GitLab CI/CD for specific use cases. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 1d279436d2c..6958b69061a 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -30,19 +30,23 @@ When a branch is protected, the default behavior enforces these restrictions on |:-------------------------|:------------------------------------------------------------------| | Protect a branch | At least the Maintainer role. | | Push to the branch | Anyone with **Allowed** permission. (1) | -| Force push to the branch | No one. | +| Force push to the branch | No one. (3) | | Delete the branch | No one. (2) | 1. Users with the Developer role can create a project in a group, but might not be allowed to initially push to the [default branch](repository/branches/default.md). 1. No one can delete a protected branch using Git commands, however, users with at least Maintainer role can [delete a protected branch from the UI or API](#delete-a-protected-branch). +1. If the `group_protected_branches` feature flag is enabled _and_ the same branch is + protected at both the group and project levels, force push settings configured + for that branch at the project level are ignored. All other protections continue + to use project level settings. ### When a branch matches multiple rules When a branch matches multiple rules, the **most permissive rule** determines the level of protection for the branch. For example, consider these rules, which include -[wildcards](#configure-multiple-protected-branches-by-using-a-wildcard): +[wildcards](#protect-multiple-branches-with-wildcard-rules): | Branch name pattern | Allowed to merge | Allowed to push and merge | |---------------------|------------------------|-----------------| @@ -77,29 +81,59 @@ that matches `v1.x` must set `Allowed to push and merge` to `No one`, like this: Administrators can set a default branch protection level in the [Admin Area](../project/repository/branches/default.md#instance-level-default-branch-protection). -## Configure a protected branch +## Add protection to existing branches Configure protected branches for all projects in a group, or just for a project. -### For all projects in a group **(PREMIUM)** +### For one project + +Prerequisites: + +- You must have at least the Maintainer role. +- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions + on a protected branch, the group must be added to the project. + +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. 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. + + NOTE: + In GitLab Premium and Ultimate, you can also add groups or individual users + to **Allowed to merge** and **Allowed to push and merge**. + +1. Select **Protect**. + +The protected branch displays in the list of protected branches. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 behind a feature flag, disabled by default. +### For all projects in a group **(PREMIUM)** -Group owners can create protected branches for a group. These settings are inherited by all projects in the group and can't be overridden by project settings. +> [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. FLAG: On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) +To make it available, ask an administrator to +[enable the feature flag](../../administration/feature_flags.md) named `group_protected_branches`. On GitLab.com, this feature is not available. +Group owners can create protected branches for a group. These settings are inherited +by all projects in the group and can't be overridden by project settings. If a +specific branch is configured with **Allowed to force push** settings at both the +group and project levels, the **Allowed to force push** setting at the _project_ level +is ignored in favor of the group level setting. + Prerequisite: - You must have the Owner role in the group. To protect a branch for all the projects in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +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. 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. @@ -108,31 +142,12 @@ To protect a branch for all the projects in a group: The protected branch is added to the list of protected branches. -### For a project - -Prerequisite: - -- You must have at least the Maintainer role. -- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions - on a protected branch, the group must be added to the project. - -To protect a branch: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Protected branches**. -1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. -1. Select **Protect**. - -The protected branch displays in the list of protected branches. - -## Configure multiple protected branches by using a wildcard +## Protect multiple branches with wildcard rules -If both a specific rule and a wildcard rule apply to the same branch, the most -permissive rule controls how the branch behaves. For merge controls to work properly, -set **Allowed to push and merge** to a broader set of users than **Allowed to merge**. +When using wildcards, multiple rules can apply to a single branch. +If more than one rule applies to a branch, the _most permissive_ rule controls +how the branch behaves. For merge controls to work properly, set +**Allowed to push and merge** to a broader set of users than **Allowed to merge**. Prerequisite: @@ -140,8 +155,8 @@ Prerequisite: To protect multiple branches at the same time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. From the **Branch** dropdown list, type the branch name and a wildcard. For example: @@ -152,19 +167,21 @@ To protect multiple branches at the same time: | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +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. In GitLab Premium or Ultimate, you can also add groups or individual users. 1. Select **Protect**. The protected branch displays in the list of protected branches. -## Create a protected branch +## Create a new branch with protections -Users with at least the Developer role can create a protected branch. +Users with at least the Developer role can create new protected branches. Prerequisites: -- **Allowed to push and merge** is set to **No one** +- **Allowed to push and merge** is set to **No one**. - **Allowed to merge** is set to **Developers**. You can create a protected branch by using the UI or API only. @@ -173,8 +190,8 @@ from the command line or from a Git client application. To create a new branch through the user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Select **New branch**. 1. Fill in the branch name and select an existing branch, tag, or commit to base the new branch on. Only existing protected branches and commits @@ -186,8 +203,8 @@ 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). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. @@ -198,8 +215,8 @@ like the [GitLab workflow](../../topics/gitlab_flow.md). You can allow everyone with write access to push to the protected branch. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select **Developers + Maintainers**. @@ -226,8 +243,8 @@ Prerequisites: To allow a deploy key to push to a protected branch: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. 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. @@ -245,8 +262,8 @@ protected branches. To protect a new branch and enable force push: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. 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. @@ -257,23 +274,49 @@ To protect a new branch and enable force push: To enable force pushes on branches that are already protected: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. 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. +### When a branch matches multiple rules + +When a branch matches multiple rules, the **most permissive rule** determines the +level of protection for the branch. For example, consider these rules, which include +[wildcards](#protect-multiple-branches-with-wildcard-rules): + +| Branch name pattern | Allow force push | +|---------------------|------------------| +| `v1.x` | Yes | +| `v1.*` | No | +| `v*` | No | + +A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`. +As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are: + +- **Allow force push:** Of the three settings, `Yes` is most permissive, + and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*` + (which each have stricter permissions), any user that can push to this branch can also force push. + +NOTE: +Force push settings for a branch at the project level are overridden by group level settings +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)** > [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. For a protected branch, you can require at least one approval by a [Code Owner](codeowners/index.md). +If a branch is protected by multiple rules, code owner approval is required if _any_ of +the applicable rules have **Required approval from code owners** enabled. To protect a new branch and enable Code Owner's approval: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. 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. @@ -282,8 +325,8 @@ To protect a new branch and enable Code Owner's approval: To enable Code Owner's approval on branches that are already protected: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. @@ -314,8 +357,8 @@ for details about the pipelines security model. Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, type the branch name. 1. Select **Yes, delete protected branch**. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 3af475afa4f..0449c9867e2 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -31,15 +31,20 @@ Prerequisites: - You must have at least the Maintainer role for the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. 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**. 1. Enter the string to use for tag matching. Wildcards (`*`) are supported. 1. Select **Create wildcard**. -1. In **Allowed to create** , select either the users or roles that may create protected tags. +1. In **Allowed to create** , select roles that may create protected tags. + + NOTE: + In GitLab Premium and Ultimate, you can also add groups or individual users + to **Allowed to create**. + 1. Select **Protect**. The protected tag (or wildcard) displays in the **Protected tags** list. @@ -105,8 +110,8 @@ Prerequisites: To allow a deploy key to create a protected tag: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +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. From the **Tag** dropdown list, select the tag you want to protect. 1. From the **Allowed to create** list, select the deploy key. @@ -123,8 +128,8 @@ Prerequisite: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Tags**. 1. Next to the tag you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 1f85490795f..368a59e69b0 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -35,7 +35,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | -| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | +| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI integrations, such as Jenkins. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | | `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 2c52a5d743a..3e8ce009740 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -129,8 +129,9 @@ threads. Some quick actions might not be available to all subscription tiers. | `/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 | **{check-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 | **{check-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). +| `/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). ## Work items @@ -162,7 +163,8 @@ The following quick actions can be applied through the description field when ed | `/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 [with a flag](../../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. +| `/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. ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index d0c44b7e837..6bcc57d5916 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -74,8 +74,8 @@ Prerequisites: To create a release in the Releases page: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Releases** and select **New release**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Build > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. @@ -215,8 +215,8 @@ To delete a release, use either the In the UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Releases**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Deploy > Releases**. 1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index bd3cfd26f1b..c5fb3838b11 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -23,7 +23,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \ "Created using the release-cli $EXTRA_DESCRIPTION" \ --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" \ --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" \ - --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} + --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}" ``` ## Install the `release-cli` for the Shell executor **(FREE)** @@ -37,13 +37,8 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ### Install on Unix/Linux -1. Download the binary for your system from S3, in the following example for amd64 systems: - - ```shell - curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64" - ``` - - Or from the GitLab Package Registry: +1. Download the binary for your system from the GitLab Package Registry. + For example, if you use an amd64 system: ```shell curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-linux-amd64" @@ -60,7 +55,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ```shell $ release-cli -v - release-cli version 0.6.0 + release-cli version 0.15.0 ``` ### Install on Windows PowerShell @@ -74,7 +69,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av 1. Download the executable file: ```shell - PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" + PS C:\> Invoke-WebRequest -Uri "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" Directory: C:\GitLab\Release-CLI Mode LastWriteTime Length Name @@ -93,5 +88,5 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ```shell PS C:\> release-cli -v - release-cli version 0.6.0 + release-cli version 0.15.0 ``` diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index d4156de2ebe..6a9d0c73e9a 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -14,7 +14,7 @@ FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `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/alpha-beta-support.md#beta) and subject to change without notice. +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. You can use remote development to write and compile code hosted on GitLab. With remote development, you can: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index e58cc0bf6a4..100450aefe7 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -42,8 +42,8 @@ Prerequisites: To update the default branch for an individual [project](../../index.md): -1. On the top bar, select **Main menu > Projects** and find your project. -1. In the left navigation menu, go to **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Branch defaults**. For **Default branch**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request @@ -68,8 +68,9 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. 1. Select **Save changes**. @@ -84,8 +85,8 @@ overrides it. Users with the Owner role of groups and subgroups can configure the default branch name for a group: -1. On the top bar, select **Main menu > Group** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. 1. Select **Save changes**. @@ -95,6 +96,8 @@ unless a subgroup configuration overrides it. ## Protect initial default branches **(FREE SELF)** +> Full protection after initial push [added](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) at the [instance level](#instance-level-default-branch-protection) and @@ -108,6 +111,8 @@ at the [instance level](#instance-level-default-branch-protection) and 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. ### Instance-level default branch protection **(FREE SELF)** @@ -120,8 +125,9 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). 1. To allow group owners to override the instance's default branch protection, select @@ -137,8 +143,9 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand the **Default branch** section. 1. Clear the **Allow owners to manage default branch protection per group** checkbox. 1. Select **Save changes**. @@ -157,8 +164,8 @@ can be overridden on a per-group basis by the group's owner. In [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). 1. Select **Save changes**. diff --git a/doc/user/project/repository/branches/img/delete_merged_branches.png b/doc/user/project/repository/branches/img/delete_merged_branches.png Binary files differdeleted file mode 100644 index 649a758b95f..00000000000 --- a/doc/user/project/repository/branches/img/delete_merged_branches.png +++ /dev/null diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 7c09ce5c580..e43efca600a 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -29,8 +29,8 @@ Branches are the foundation of development in a project: To create a new branch from the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. On the top right, select **New branch**. 1. Enter a **Branch name**. 1. In **Create from**, select the base of your branch: an existing branch, an existing @@ -52,7 +52,7 @@ Prerequisites: To add a [default branch](default.md) to an empty project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Scroll to **The repository for this project is empty** and select the type of file you want to add. 1. In the Web IDE, make any desired changes to this file, then select **Create commit**. @@ -62,7 +62,14 @@ GitLab creates a default branch and adds your file to it. ### From an issue +Prerequisites: + +- You must have at least the Developer role in the project. + When viewing an issue, you can create an associated branch directly from that page. +Branches created this way use the +[default pattern for branch names from issues](#configure-default-pattern-for-branch-names-from-issues), +including variables. Prerequisites: @@ -70,8 +77,8 @@ Prerequisites: To create a branch from an issue: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues** (**{issues}**) and find your issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues** and find your issue. 1. Below the issue description, find the **Create merge request** dropdown list, and select **{chevron-down}** to display the dropdown list. 1. Select **Create branch**. A default **Branch name** is provided, based on the @@ -104,8 +111,8 @@ You can manage your branches: To view and manage your branches in the GitLab user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. On this page, you can: @@ -142,8 +149,8 @@ Prerequisites: To view the **Branch rules overview** list: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Branch Rules** to view all branches with protections. - To add protections to a new branch: 1. Select **Add branch rule**. @@ -193,8 +200,9 @@ Prerequisites: To change the default pattern for branches created from issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository** and expand **Branch defaults**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. +1. Expand **Branch defaults**. 1. Scroll to **Branch name template** and enter a value. The field supports these variables: - `%{id}`: The numeric ID of the issue. - `%{title}`: The title of the issue, modified to use only characters acceptable in Git branch names. @@ -230,8 +238,8 @@ new changes. It uses the merge base, not the actual commit content, to compare b To compare branches in a repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Compare revisions**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Compare revisions**. 1. Select the **Source** branch to search for your desired branch. Exact matches are shown first. You can refine your search with operators: - `^` matches the beginning of the branch name: `^feat` matches `feat/user-authentication`. @@ -244,15 +252,22 @@ To compare branches in a repository: ## Delete merged branches -![Delete merged branches](img/delete_merged_branches.png) +Merged branches can be deleted in bulk if they meet all of these criteria: + +- They are not [protected branches](../../protected_branches.md). +- They have been merged into the project's default branch. + +Prerequisites: + +- You must have at least the Developer role in the project. -This feature allows merged branches to be deleted in bulk. Only branches that -have been merged into the project's default branch and -[are not protected](../../protected_branches.md) are deleted as part of -this operation. +To do this: -It's particularly useful to clean up old branches that were not deleted -automatically when a merge request was merged. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. +1. On the upper right corner of the page, select **More** **{ellipsis_v}**. +1. Select **Delete merged branches**. +1. In the modal window, enter the word `delete` to confirm, then select **Delete merged branches**. ## Related topics @@ -308,8 +323,8 @@ Error: Could not set the default branch. Do you have a branch named 'HEAD' in yo To fix this problem: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Search for a branch named `HEAD`. 1. Make sure the branch has no uncommitted changes. 1. Select **Delete branch**, then **Yes, delete branch**. diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md index 5de55db5ad4..dd1fa3f4c8b 100644 --- a/doc/user/project/repository/code_suggestions.md +++ b/doc/user/project/repository/code_suggestions.md @@ -7,19 +7,21 @@ type: index, reference # Code Suggestions (Beta) **(FREE SAAS)** -> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/alpha-beta-support.md#beta) for early access Ultimate customers. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/alpha-beta-support.md#beta). +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/experiment-beta-support.md#beta) for early access Ultimate customers. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/experiment-beta-support.md#beta). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1. +> - [Default to third-party AI services](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. WARNING: -This feature is in [Beta](/ee/policy/alpha-beta-support.md#beta). -Code Suggestions use generative AI to suggest code while you're developing. -Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. +This feature is in [Beta](/ee/policy/experiment-beta-support.md#beta). +Due to high demand, this feature may have unscheduled downtime and Code Suggestions in IDEs may be delayed. Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your feedback. -Use Code Suggestions to write code more efficiently by viewing code suggestions +Code Suggestions use generative AI to suggest code while you're developing. +Use Code Suggestions to write code more efficiently by viewing Code Suggestions as you type. Depending on the cursor position, the extension either: - Provides entire code snippets, like generating functions. @@ -27,47 +29,68 @@ as you type. Depending on the cursor position, the extension either: To accept a suggestion, press <kbd>Tab</kbd>. -Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. +Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. [Additional IDE extension support](https://gitlab.com/groups/gitlab-org/-/epics/10542) is planned for the near future. ## Supported languages -Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). The best results from Code Suggestions are expected for these languages: +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). + +Language support varies depending on which AI model serves Code Suggestions. To use Code Suggestions entirely within GitLab cloud infrastructure, disable third-party AI services. To receive higher quality suggestions, [enable third-party AI services](#third-party-ai-services-controls). -- C/C++ -- C# -- Go -- Java -- JavaScript -- Python -- PHP -- Ruby -- Rust -- Scala -- TypeScript +The best results from Code Suggestions are expected for these languages: + +- **Third-party AI services (Google Codey)**: Go, Google Cloud CLI, Google SQL, Java, JavaScript, Kubernetes Resource Model (KRM), Python, Terraform, TypeScript. +- **GitLab first-party AI model**: C/C++, C#, Go, Java, JavaScript, Python, PHP, Ruby, Rust, Scala, TypeScript. Suggestions may be mixed for other languages. Using natural language code comments to request completions may also not function as expected. -GitLab is continuously improving the model and expects to support an additional seven languages soon, as well as natural language code comments. +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. + +We are making improvements to the Code Suggestions underlying AI model weekly to improve the quality of suggestions. Please remember that AI is non-deterministic, so you may not get the same suggestion week to week. Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). +## Enable Code Suggestions for an individual user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](/ee/policy/experiment-beta-support.md#beta). + +Each user can enable Code Suggestions for themselves: + +1. On the left sidebar, select your avatar. +1. On the left sidebar, select **Preferences**. +1. In the **Code Suggestions** section, select **Enable Code Suggestions**. +1. Select **Save changes**. + +NOTE: +If Code Suggestions is [enabled for the group](../../group/manage.md#enable-code-suggestions), the group setting overrides the user setting. + +## Enable Code Suggestions in WebIDE + +Prerequisites: + +- Code Suggestions must be [enabled for the top-level group](../../group/manage.md#enable-code-suggestions). +- Code Suggestions must be [enabled for your user account](#enable-code-suggestions-for-an-individual-user). +- You must be a GitLab team member. + +Code Suggestions work automatically in the [GitLab WebIDE](../../project/web_ide/index.md) if the above prerequisites are met. To disable Code Suggestions in the WebIDE, disable the user account setting. + +NOTE: +Disabling in the WebIDE will also disable in any other IDEs you use locally like VS Code. Support for [more granular control per IDE](https://gitlab.com/groups/gitlab-org/-/epics/10624) is proposed. + ## Enable Code Suggestions in VS Code Prerequisites: -- Your group owner must enable the [group level code suggestions setting](../../group/manage.md#group-code-suggestions). -- You must have [a personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` and `read_user` scopes. +- Code Suggestions must be [enabled for the top-level group](../../group/manage.md#enable-code-suggestions). +- Code Suggestions must be [enabled for your user account](#enable-code-suggestions-for-an-individual-user). +- Completed the [setup instructions](https://gitlab.com/gitlab-org/gitlab-vscode-extension#setup) for the GitLab Visual Studio Code Extension. To enable Code Suggestions in VS Code: -1. Download and configure the +1. Download and install the [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) for Visual Studio Code. -1. In **GitLab: Add Account to VS Code on Mac**, add your GitLab work account to the VS Code extension: - - In macOS, press <kbd>Shift</kbd> + <kbd>Command</kbd> + <kbd>P</kbd>. - - In Windows, press <kbd>Shift</kbd> + <kbd>Control</kbd> + <kbd>P</kbd>. -1. Provide your GitLab instance URL. A default is provided. -1. Provide your personal access token. +1. Complete the [setup instructions](https://gitlab.com/gitlab-org/gitlab-vscode-extension#setup) for the extension. 1. After your GitLab account connects successfully, in the left sidebar, select **Extensions**. 1. Find the **GitLab workflow** extension, select **Settings** (**{settings}**), and select **Extension Settings**. 1. Enable **GitLab > AI Assisted Code Suggestions**. @@ -81,6 +104,51 @@ Start typing and receive suggestions for your GitLab projects. <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> </figure> +## Enable Code Suggestions in other IDEs and editors + +We have experimental support for Code Suggestions in Visual Studio, JetBrains, Neovim, Emacs, Sublime, etc. + +More details in this [blog](https://about.gitlab.com/blog/2023/06/01/extending-code-suggestions/). + +## Why aren't Code Suggestions displayed? + +If Code Suggestions are not displayed, try the following troubleshooting steps. + +In GitLab, ensure Code Suggestions is enabled: + +- [For your user account](#enable-code-suggestions-for-an-individual-user). +- [For *all* top-level groups your account belongs to](../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. + +In VS Code: + +- Ensure [your IDE is configured properly](#enable-code-suggestions-in-vs-code). + +To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. + +### Authentication troubleshooting + +If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, specifically the token system. To resolve the issue, please follow these troubleshooting steps: + +- Remove the existing PAT from your GitLab account settings. +- Reauthorize your GitLab account in VSCode using OAuth. +- Test the code suggestions feature with different file extensions to verify if the issue is resolved. + +## Third-party AI services controls + +Organizations can opt to use Code Suggestions entirely within GitLab cloud infrastructure. This option can be controlled with the top-level group [Third-party AI setting](../../group/manage.md#enable-third-party-ai-features). + +Having the third-party AI setting enabled will allow Code Suggestions to use third-party AI services, which is likely to produce higher quality results. Please note that language support varies between the two options and will change over time. + +To use Code Suggestions entirely within GitLab’s cloud infrastructure, disable third-party AI services. You can disable Code Suggestions entirely in [your user profile settings](#enable-code-suggestions-for-an-individual-user). + +## Stability and performance + +This feature is currently in [Beta](/ee/policy/experiment-beta-support.md#beta). +While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, +we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime +of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + ## Code Suggestions data usage Code Suggestions is a generative artificial intelligence (AI) model hosted on GitLab.com. @@ -89,8 +157,12 @@ Your personal access token enables a secure API connection to GitLab.com. This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, and the generated suggestion is transmitted back to VS Code. +Depending on your settings, different ML models will be used to provide Code Suggestions. GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) for third-party AI powered Code Suggestions. The sections below refer only to GitLab first-party AI Model. + ### Data privacy +This section applies only to customers who have third-party AI services disabled. + Code Suggestions operate completely in the GitLab.com infrastructure, providing the same level of [security](https://about.gitlab.com/security/) as any other feature of GitLab.com, and processing any personal data in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). @@ -103,6 +175,8 @@ Your data also never leaves GitLab.com. All training and inference is done in Gi ### Training data +This section applies only to customers who have third-party AI services disabled. + Code Suggestions uses open source pre-trained base models from the [CodeGen family](https://openreview.net/forum?id=iaYcJKpY2B_) including CodeGen-MULTI and CodeGen-NL. We then re-train and fine-tune these base models with a customized open source dataset to enable multi-language @@ -111,41 +185,29 @@ programming languages from [The Pile](https://pile.eleuther.ai/) and the [Google BigQuery source code dataset](https://cloud.google.com/blog/topics/public-datasets/github-on-bigquery-analyze-all-the-open-source-code). We then process this raw dataset against heuristics that aim to increase the quality of the dataset. -The Code Suggestions model is not trained on GitLab customer data. - -### Off by default - -Code Suggestions are off by default and require a group owner to enable the feature with a group-level setting. - -After the group-level setting is enabled, developers using Visual Studio Code with the -[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) can connect -to GitLab.com by using a GitLab -[personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` -and `read_user` scopes. +The Code Suggestions model is not trained on GitLab customer or user data. ## Progressive enhancement -This feature is designed as a progressive enhancement to the existing VS Code GitLab Workflow plugin. +This feature is designed as a progressive enhancement to developers IDEs. Code Suggestions offer a completion if the machine learning engine can generate a recommendation. In the event of a connection issue or model inference failure, the feature gracefully degrades. -Code Suggestions do not prevent you from writing code in VS Code. +Code Suggestions do not prevent you from writing code in your IDE. ### Internet connectivity -Code Suggestions only work when you have internet connectivity and can access GitLab.com. -Code Suggestions are not available for self-managed customers, nor customers operating within an offline environment. +Code Suggestions does not work with offline environments. -### Stability and performance +To use Code Suggestions: -This feature is currently in [Beta](/ee/policy/alpha-beta-support.md#beta). -While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, -we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime -of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to -mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. +- On GitLab.com, you must have an internet connection and be able to access GitLab. +- In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. + +[Self-managed support via a proxy to GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/10528) has been proposed. ### Model accuracy and quality -While in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +Regardless of whether third-party AI services are enabled, while in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. We strongly encourage all beta users to leverage GitLab native [Code Quality Scanning](../../../ci/testing/code_quality.md) and [Security Scanning](../../application_security/index.md) capabilities. @@ -174,6 +236,7 @@ However, Code Suggestions may generate suggestions that are: We are also aware of specific situations that can produce unexpected or incoherent results including: +- Suggestions written in the middle of existing functions, or "fill in the middle." - Suggestions based on natural language code comments. - Suggestions that mixed programming languages in unexpected ways. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index e22dc549a4a..dece959bdc9 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -14,8 +14,8 @@ File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fu To search for a file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. In the upper right, select **Find file**. 1. In the search box, start typing the filename. 1. From the dropdown list, select the file. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 74d765fa7fe..a6bb02989a3 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -54,17 +54,13 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates ### From the UI -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `synchronize_fork`. -On GitLab.com, this feature is available for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 16.0. Feature flag `synchronize_fork` removed. To update your fork from the GitLab UI: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the secondary menu, select **Personal**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. Select the fork you want to update. 1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**) information box to determine if your fork is ahead, behind, or both. In this example, @@ -185,8 +181,8 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To remove a fork relationship: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Remove fork relationship** section, select **Remove fork relationship**. 1. To confirm, enter the project path and select **Confirm**. @@ -199,7 +195,6 @@ to share objects with another repository: ## Related topics -- GitLab blog post: [Keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/) - GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/32469) ## Troubleshooting diff --git a/doc/user/project/repository/geojson.md b/doc/user/project/repository/geojson.md new file mode 100644 index 00000000000..723121bc923 --- /dev/null +++ b/doc/user/project/repository/geojson.md @@ -0,0 +1,19 @@ +--- +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 +type: reference +--- + +# GeoJSON files **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14134) in GitLab 16.1. + +A GeoJSON file is a format for encoding geographical data structures using JavaScript Object Notation (JSON). +It is commonly used for representing geographic features, such as points, lines, and polygons, along with their associated attributes. + +When added to a repository, files with a `.geojson` extension are rendered as a map containing the GeoJSON data when viewed in GitLab. + +Map data comes from [OpenStreetMap](https://www.openstreetmap.org/) under the [Open Database License](https://www.openstreetmap.org/copyright). + +![GeoJSON file rendered as a map](img/geo_json_file_rendered_v16_1.png) diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index fbf29bddd46..baac2a788be 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -10,7 +10,16 @@ description: "Documentation on Git file blame." [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and -commit hash. To view it for a file: +commit hash. + +## View blame for a file + +Prerequisites: + +- The file type must be text-based. The GitLab UI does not display + `git blame` results for binary files. + +To view the blame for a file: 1. Go to your project's **Repository > Files**. 1. Select the file you want to review. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index a2dd2488961..839ab33808b 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -121,7 +121,7 @@ To add a GPG key to your user settings: 1. Sign in to GitLab. 1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **GPG Keys** (**{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: @@ -226,11 +226,11 @@ Prerequisites: You can review commits for a merge request, or for an entire project: 1. To review commits for a project: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Repository > Commits**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Commits**. 1. To review commits for a merge request: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Merge requests**, then select your merge request. 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** or **Unverified** badge, depending on the verification status of the GPG @@ -255,7 +255,7 @@ To revoke a GPG key: 1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. ## Remove a GPG key @@ -270,7 +270,7 @@ To remove a GPG key from your account: 1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **GPG Keys** (**{key}**). 1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. If you must unverify both future and past commits, diff --git a/doc/user/project/repository/img/geo_json_file_rendered_v16_1.png b/doc/user/project/repository/img/geo_json_file_rendered_v16_1.png Binary files differnew file mode 100644 index 00000000000..b67a7bc3fda --- /dev/null +++ b/doc/user/project/repository/img/geo_json_file_rendered_v16_1.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 1526c7b4dc2..d3d9b202e63 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,7 +25,7 @@ GitLab. ## Cleaner diffs and raw diffs -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. > - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 0563f747e8d..550d4535adb 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -44,7 +44,7 @@ and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 9f72b8f29b2..733310a0b4d 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -34,14 +34,14 @@ Mirror a repository when: ## Create a repository mirror -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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. Enter a **Git repository URL**. For security reasons, the URL to the original repository is only displayed to users with the Maintainer role @@ -59,13 +59,38 @@ Prerequisite: 1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) to ensure it is correct. 1. To prevent force-pushing over diverged refs, select [**Keep divergent refs**](push.md#keep-divergent-refs). -1. Optional. Select [**Mirror only protected branches**](#mirror-only-protected-branches). +1. Optional. To limit the number of branches mirrored, select + **Mirror only protected branches** or enter a regex in **Mirror specific branches**. 1. Select **Mirror repository**. If you select `SSH public key` as your authentication method, GitLab generates a public key for your GitLab repository. You must provide this key to the non-GitLab server. For more information, see [Get your SSH public key](#get-your-ssh-public-key). +### Mirror only protected branches + +You can choose to mirror only the +[protected branches](../../protected_branches.md) in the mirroring project, +either from or to your remote repository. For [pull mirroring](pull.md), +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)** + +> - 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. + +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is available. + +To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), +enter a regular expression into the **Mirror specific branches** field. Branches with names that +do not match the regular expression are not mirrored. + ## Update a mirror When the mirror repository is updated, all new branches, tags, and commits are visible in the @@ -88,37 +113,13 @@ Prerequisite: - You must have at least the Maintainer role for the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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. Scroll to **Mirrored repositories** and identify the mirror to update. 1. Select **Update now** (**{retry}**): ![Repository mirroring force update user interface](img/repository_mirroring_force_update.png) -## Mirror only protected branches - -You can choose to mirror only the -[protected branches](../../protected_branches.md) in the mirroring project, -either from or to your remote repository. For [pull mirroring](pull.md), -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 - -> - 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. - -FLAG: -On self-managed GitLab, by default the field `mirror_branch_regex` is available. -To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) -named `mirror_only_branches_match_regex`. -On GitLab.com, this feature is available. - -To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), -enter a regular expression into the **Mirror specific branches** field. Branches with names that -do not match the regular expression are not mirrored. - ## Authentication methods for mirrors When you create a mirror, you must configure the authentication method for it. @@ -155,8 +156,8 @@ When you mirror a repository and select the **SSH public key** as your authentication method, GitLab generates a public key for you. The non-GitLab server needs this key to establish trust with your GitLab repository. To copy your SSH public key: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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. Scroll to **Mirrored repositories**. 1. Identify the correct repository, and select **Copy SSH public key** (**{copy-to-clipboard}**). @@ -183,6 +184,7 @@ for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) +- [Codeberg](https://docs.codeberg.org/security/ssh-fingerprint/) - [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints) - [GitLab.com](../../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) @@ -263,8 +265,8 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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: @@ -344,8 +346,8 @@ Prerequisites: To resolve the issue: 1. [Verify the host key](#verify-a-host-key). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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. To refresh the keys, either: diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 2b8470b9e3d..1463e0de0f1 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -60,8 +60,8 @@ Prerequisite: with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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. Enter the **Git repository URL**. Include the username in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 11093958650..9da8ce7acc5 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -34,8 +34,8 @@ displays an error. To set up push mirroring for an existing project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > 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. Enter a repository URL. 1. In the **Mirror direction** dropdown list, select **Push**. @@ -79,8 +79,15 @@ To configure a mirror from GitLab to GitHub: 1. Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `public_repo` selected. -1. Enter a **Git repository URL** with this format: - `https://<your_access_token>@github.com/<github_group>/<github_project>.git`. +1. Enter a **Git repository URL** with this format, changing the variables as needed: + + ```plaintext + https://USERNAME@github.com/GROUP/PROJECT.git + ``` + + - `USERNAME`: The username of the owner of the personal access token. + - `GROUP`: The group on GitHub. + - `PROJECT`: The project on GitHub. 1. For **Password**, enter your GitHub personal access token. 1. Select **Mirror repository**. @@ -149,7 +156,7 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. 1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. -1. On the left sidebar, select **Settings > Repository**, and then expand **Mirroring repositories**. +1. Select **Settings > Repository**, and then expand **Mirroring repositories**. 1. Fill in the **Git repository URL** field using this format: ```plaintext diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 28afba375fc..fbadc9b84a3 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -19,6 +19,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. For custom push rules use [server hooks](../../../administration/server_hooks.md). @@ -36,8 +37,9 @@ Prerequisite: To create global push rules: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Push Rules**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Push Rules**. 1. Expand **Push rules**. 1. Set the rule you want. 1. Select **Save push rules**. @@ -48,8 +50,8 @@ The push rule of an individual project overrides the global push rule. To override global push rules for a specific project, or to update the rules for an existing project to match new global push rules: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Push rules**. 1. Set the rule you want. 1. Select **Save push rules**. 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 4bebe4c1a97..ce3a5ee9916 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 @@ -1,6 +1,6 @@ --- -stage: Systems -group: Gitaly +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 --- @@ -74,7 +74,7 @@ To purge files from a GitLab repository: 1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell - git clone --bare /path/to/project.bundle + git clone --bare --mirror /path/to/project.bundle ``` 1. Go to the `project.git` directory: @@ -134,6 +134,12 @@ To purge files from a GitLab repository: Repeat this step and all following steps (including the [repository cleanup](#repository-cleanup) step) every time you run any `git filter-repo` command. +1. To allow you to force push the changes you need to unset the mirror flag: + + ```shell + git config --unset remote.origin.mirror + ``` + 1. Force push your changes to overwrite all branches on GitLab: ```shell @@ -160,13 +166,13 @@ To purge files from a GitLab repository: Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. -1. Wait at least 30 minutes, because the repository cleanup process only processes object older than 30 minutes. -1. Run [repository cleanup](#repository-cleanup). +1. Wait at least 30 minutes before attempting the next step. +1. Run [repository cleanup](#repository-cleanup). This process only cleans up objects + that are more than 30 minutes old. See [Space not being freed](#space-not-being-freed) + for more information. ## Repository cleanup -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. - Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a @@ -178,6 +184,10 @@ of the operation. This happens automatically, but submitting the cleanup request fails if any writes are ongoing, so cancel any outstanding `git push` operations before continuing. +WARNING: +Removing internal Git references results in associated merge request commits, pipelines, and changes details +no longer being available. + To clean up a repository: 1. Go to the project for the repository. @@ -300,3 +310,17 @@ end puts "#{artifact_storage} bytes" ``` + +### Space not being freed + +The process defined on this page can decrease the size of repository exports +decreasing, but the usage in the file system appearing unchanged in both the Web UI and terminal. + +The process leaves many unreachable objects remaining in the repository. +Because they are unreachable, they are not included in the export, but they are +still stored in the file system. These files are pruned after a grace period of +two weeks. Pruning deletes these files and ensures your storage usage statistics +are accurate. + +To expedite this process, see the +['Prune Unreachable Objects' housekeeping task](../../../administration/housekeeping.md). diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index f2ce80263c8..8f29845fd9b 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -93,10 +93,10 @@ You can review commits for a merge request, or for an entire project, to confirm they are signed: 1. To review commits for a project: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Repository > Commits**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Commits**. 1. To review commits for a merge request: - 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Merge requests**, then select your merge request. 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index e252a9a433b..8c6774408e6 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -44,15 +44,15 @@ In the GitLab UI, each tag displays: To view all existing tags for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Tags**. ## View tagged commits in the commits list > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Commits**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Commits**. 1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. This example shows a commit tagged `v1.26.0`: @@ -88,8 +88,8 @@ To create either a lightweight or annotated tag from the command line, and push To create a tag from the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Tags**. 1. Select **New tag**. 1. Provide a **Tag name**. 1. For **Create from**, select an existing branch name, tag, or commit SHA. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index dc988846676..7b2dcd04982 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -25,7 +25,7 @@ for any change you commit through the Web Editor. To create a text file in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. @@ -35,8 +35,8 @@ To create a text file in the Web Editor: ### Create a file from a template -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Next to the project name, select the plus icon (**{plus}**) to display a dropdown list, then select **New file** from the list. 1. For **Filename**, provide one of the filenames that GitLab provides a template for: @@ -56,15 +56,9 @@ To create a text file in the Web Editor: To edit a text file in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Go to your file. -1. In the upper-right corner of the file, select **Edit**. - - If **Edit** is not visible: - - 1. Next to **Open in Web IDE** or **Open in Gitpod**, select the down arrow (**{chevron-lg-down}**). - 1. From the dropdown list, select **Edit** as your default setting. - 1. Select **Edit**. +1. In the upper right, select **Edit > Edit single file**. ### Keyboard shortcuts @@ -111,7 +105,7 @@ To upload a binary file in the Web Editor: <!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> <!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. 1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -121,7 +115,7 @@ To upload a binary file in the Web Editor: To create a directory in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New directory**. 1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -131,7 +125,7 @@ To create a directory in the Web Editor: To create a [branch](branches/index.md) in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New branch**. 1. Complete the fields. @@ -142,7 +136,7 @@ To create a [branch](branches/index.md) in the Web Editor: You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New tag**. 1. Complete the fields. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index bd5c8214e68..8d525965f96 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -54,11 +54,13 @@ Prerequisites: [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 top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +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. @@ -101,7 +103,8 @@ visible in the email template. For more information, see #### Thank you email -> `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{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. When a user submits an issue through Service Desk, GitLab sends a **thank you email**. @@ -110,20 +113,23 @@ directory in your repository, create a file named `thank_you.md`. You can use these placeholders to be automatically replaced in each email: -- `%{ISSUE_ID}`: issue IID -- `%{ISSUE_PATH}`: project path appended with the issue IID -- `%{ISSUE_DESCRIPTION}`: issue description based on the original email -- `%{UNSUBSCRIBE_URL}`: unsubscribe URL -- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) +- `%{ISSUE_ID}`: Issue IID. +- `%{ISSUE_PATH}`: Project path appended with the issue IID. +- `%{ISSUE_URL}`: URL to the issue. External participants can only view the issue if the project is public + and issue is not confidential (Service Desk issues are confidential by default). +- `%{ISSUE_DESCRIPTION}`: Issue description based on the original email. +- `%{UNSUBSCRIBE_URL}`: Unsubscribe URL. +- `%{SYSTEM_HEADER}`: [System header message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{SYSTEM_FOOTER}`: [System footer message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{ADDITIONAL_TEXT}`: [Custom additional text](../admin_area/settings/email.md#custom-additional-text). Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), the response email does not contain the issue link. #### New note email -> `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{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. When a user-submitted issue receives a new comment, GitLab sends a **new note email**. @@ -132,17 +138,19 @@ directory in your repository, create a file named `new_note.md`. You can use these placeholders to be automatically replaced in each email: -- `%{ISSUE_ID}`: issue IID -- `%{ISSUE_PATH}`: project path appended with the issue IID -- `%{ISSUE_DESCRIPTION}`: issue description at the time email is generated. +- `%{ISSUE_ID}`: Issue IID. +- `%{ISSUE_PATH}`: Project path appended with the issue IID. +- `%{ISSUE_URL}`: URL to the issue. External participants can only view the issue if the project is public + and issue is not confidential (Service Desk issues are confidential by default). +- `%{ISSUE_DESCRIPTION}`: Issue description at the time email is generated. If a user has edited the description, it might contain sensitive information that is not intended to be delivered to external participants. Use this placeholder only if you never modify descriptions or your team is aware of the template design. -- `%{NOTE_TEXT}`: note text -- `%{UNSUBSCRIBE_URL}`: unsubscribe URL -- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) +- `%{NOTE_TEXT}`: Note text. +- `%{UNSUBSCRIBE_URL}`: Unsubscribe URL. +- `%{SYSTEM_HEADER}`: [System header message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{SYSTEM_FOOTER}`: [System footer message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{ADDITIONAL_TEXT}`: [Custom additional text](../admin_area/settings/email.md#custom-additional-text). ### Use a custom template for Service Desk issues @@ -163,8 +171,8 @@ Prerequisite: To use a custom description template with Service Desk: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +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. @@ -174,6 +182,11 @@ Behind the scenes, Service Desk works by the special Support Bot user creating i 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 @@ -181,8 +194,8 @@ this name in the `From` header. The default display name is `GitLab Support Bot` To edit the custom email display name: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +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**. @@ -225,9 +238,10 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip 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 an Omnibus installation running GitLab 15.3, you must generate a secret file. +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 an Omnibus installation generates this secret file automatically, so no secret file configuration setting is needed. +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 @@ -406,7 +420,7 @@ Service Desk can be configured to read Microsoft Exchange Online mailboxes with 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). -- Example for Omnibus GitLab installations: +- Example for Linux package installations: ```ruby gitlab_rails['service_desk_email_enabled'] = true @@ -455,8 +469,8 @@ Prerequisites: - You must have configured a [custom mailbox](#configure-a-custom-mailbox). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +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**. @@ -472,6 +486,138 @@ 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). @@ -481,8 +627,8 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo To check what the Service Desk email address is for your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Service Desk**. +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. @@ -533,8 +679,8 @@ Prerequisites: To view Service Desk issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Service Desk**. +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 @@ -570,7 +716,7 @@ In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. 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#modify-issue-confidentiality). +[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. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 958246908bc..6cc2b51f077 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -86,8 +86,9 @@ Before you can migrate projects on a self-managed GitLab instance using file exp To enable file exports as an import source for the destination instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. 1. Select the **GitLab export** checkbox. @@ -112,8 +113,8 @@ Prerequisites: To export a project and its data, follow these steps: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Export project**. 1. After the export is generated, you should receive an email with a link to download the file. @@ -181,6 +182,8 @@ Items that are **not** exported include: - Secure files - [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700) (for example, pushing and creating tags) - Security policies associated with your project +- Links between issues and linked items +- Links to related merge requests Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and [instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index f89c2a1eaaa..8deb05c45ef 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -13,8 +13,8 @@ Use the **Settings** page to manage the configuration options in your [project]( You must have at least the Maintainer role to view project settings. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. To display all settings in a section, select **Expand**. 1. Optional. Use the search box to find a setting. @@ -23,8 +23,8 @@ You must have at least the Maintainer role to view project settings. Use the project general settings to edit your project details. 1. Sign in to GitLab with at least the Maintainer role. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. In the **Project name** text box, enter your project name. 1. In the **Project description** text box, enter your project description. 1. Under **Project avatar**, to change your project avatar, select **Choose file**. @@ -35,8 +35,8 @@ Use topics to categorize projects and find similar new projects. To assign topics to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings** > **General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings** > **General**. 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. @@ -49,9 +49,9 @@ If you're an instance administrator, you can administer all project topics from compliance framework using either: - The GitLab UI: - 1. On the top bar, select **Main menu > Projects > View all projects** and find your project. - 1. On the left sidebar, select **Settings** > **General**. - 1. Expand the **Compliance frameworks** section. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings** > **General**. + 1. Expand **Compliance frameworks**. 1. Select a compliance framework. 1. Select **Save changes**. - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the @@ -59,13 +59,16 @@ compliance framework using either: compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user has the correct permissions. The GitLab UI presents a read-only view to discourage this behavior. +NOTE: +Frameworks can not be added to projects in personal namespaces. + ## Configure project visibility, features, and permissions To configure visibility, features, and permissions for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. To change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. 1. To allow users to request access to the project, select the **Users can request access** checkbox. 1. Use the [toggles](#project-feature-settings) to enable or disable features in the project. @@ -130,9 +133,9 @@ In some environments, users can submit a [CVE identifier request](../../applicat To disable the CVE identifier request option in issues in your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. 1. Select **Save changes**. @@ -142,9 +145,9 @@ Prerequisites: - You must be an Owner of the project to disable email notifications related to the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Clear the **Disable email notifications** checkbox. ## Configure merge request settings for a project @@ -156,7 +159,7 @@ Configure your project's merge request settings: - Enable [merge request approvals](../merge_requests/approvals/index.md). - Enable [status checks](../merge_requests/status_checks.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). +- Enable [merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). @@ -184,8 +187,8 @@ other features are read-only. Archived projects are also hidden from project lis To archive a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Archive project** section, select **Archive project**. 1. To confirm, select **OK**. @@ -200,7 +203,8 @@ Prerequisites: - To unarchive a project, you must be an administrator or a project Owner. 1. Find the archived project. - 1. On the top bar, select **Main menu > Projects > View all projects**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **View all your projects**. 1. Select **Explore projects**. 1. In the **Sort projects** dropdown list, select **Show archived projects**. 1. In the **Filter by name** field, enter the project name. @@ -225,9 +229,9 @@ When you change the repository path, users may experience issues if they push to To rename a repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Advanced** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. 1. In the **Change path** text box, edit the path. 1. Select **Change path**. @@ -238,8 +242,8 @@ In merge requests, you can change the default behavior so that the To set this default: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Select **Enable "Delete source branch" option by default**. 1. Select **Save changes**. @@ -249,7 +253,7 @@ When you transfer a project to another namespace, you move the project to a diff Prerequisites: -- You must have at least the Maintainer role for the [group](../../group/manage.md#create-a-group) to which you are transferring. +- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) to which you are transferring. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). @@ -258,8 +262,8 @@ Prerequisites: To transfer a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Under **Transfer project**, choose the namespace to transfer the project to. 1. Select **Transfer project**. @@ -281,6 +285,11 @@ When you transfer a project from a namespace licensed for GitLab SaaS Premium or ## Delete a project +> - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. +> - Default deletion behavior for projects changed to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. +> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. + You can mark a project to be deleted. Prerequisite: @@ -289,37 +298,34 @@ Prerequisite: To delete a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. -1. In the "Delete project" section, select **Delete project**. -1. Confirm the action when asked to. +1. In the **Delete this project** section, select **Delete project**. +1. In the confirmation message text field, enter the name of the project as instructed, and select **Yes, delete project**. -This action deletes a project including all associated resources (such as issues and merge requests). - -WARNING: -The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) -in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +This action deletes the project and all associated resources (such as issues and merge requests). ### Delayed project deletion **(PREMIUM)** > - [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. +> - 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. -Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether -delayed project deletion is enabled for a particular project: +Projects in a group (not a personal namespace) can be deleted after a delay period. -- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#delayed-project-deletion). - You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the - delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). -- Group [settings](../../group/manage.md#enable-delayed-project-deletion) to enabled delayed project deletion for all - projects in the group. +On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. +On SaaS, there is a non-adjustable default retention period of seven days. ### Delete a project immediately -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. +> - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. + +If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again. -If you don't want to wait, you can delete a project immediately. +In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. +If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately. Prerequisites: @@ -328,16 +334,11 @@ Prerequisites: To immediately delete a project marked for deletion: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. -1. In the "Permanently delete project" section, select **Delete project**. -1. Confirm the action when asked to. - -The following are deleted: - -- Your project and its repository. -- All related resources including issues and merge requests. +1. In the **Delete this project** section, select **Delete project**. +1. In the confirmation message text field, enter the name of the project as instructed, as select **Yes, delete project**. ## Restore a project **(PREMIUM)** @@ -345,7 +346,9 @@ The following are deleted: To restore a project marked for deletion: -1. Navigate to your project, and select **Settings > General > Advanced**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. 1. In the Restore project section, select **Restore project**. ## Monitor settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 178500093e2..7fd8fdf3a00 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -11,6 +11,7 @@ type: reference, howto > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. +> - [Became available in trial subscriptions](https://gitlab.com/gitlab-org/gitlab/-/issues/386041) in GitLab 16.1. Default prefix added. Project access tokens are similar to passwords, except you can [limit access to resources](#scopes-for-a-project-access-token), select a limited role, and provide an expiry date. @@ -32,12 +33,9 @@ The ability to create project access tokens without expiry was [deprecated](http You can use project access tokens: -- On GitLab SaaS: If you have the Premium or Ultimate license tier. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). -- On self-managed instances of GitLab: With any license tier. If you have the Free tier: - - Review your security and compliance policies around - [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). - - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to - lower potential abuse. +- On GitLab SaaS: If you have the Premium or Ultimate license tier, only one project access token is available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab: With any license tier. If you have the Free tier, + consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. You cannot use project access tokens to create other group, project, or personal access tokens. @@ -57,8 +55,8 @@ all projects that have visibility level set to [Internal](../../public_access.md To create a project access token: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Access Tokens**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Enter an expiry date for the token. - The token expires on that date at midnight UTC. @@ -75,8 +73,8 @@ A project access token is displayed. Save the project access token somewhere saf To revoke a project access token: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Access Tokens**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Access Tokens**. 1. Next to the project access token to revoke, select **Revoke**. ## Scopes for a project access token @@ -98,8 +96,8 @@ The scope determines the actions you can perform when you authenticate with a pr To enable or disable project access token creation for all projects in a top-level group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Allow project and group access token creation**. @@ -112,7 +110,7 @@ Even when creation is disabled, you can still use and revoke existing project ac Bot users for projects are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). Each time you create a project access token, a bot user is created and added to the project. -These bot users do not count as licensed seats. +This user is not a billable user, so it does not count toward the license limit. The bot users for projects have [permissions](../../permissions.md#project-members-permissions) that correspond with the selected role and [scope](#scopes-for-a-project-access-token) of the project access token. @@ -139,4 +137,4 @@ See also [Bot users for groups](../../group/settings/group_access_tokens.md#bot- ## Token availability -Project access tokens are only available in paid subscriptions, and not available in trial subscriptions. For more information, see the ["What is included" section of the GitLab Trial FAQ](https://about.gitlab.com/free-trial/#what-is-included-in-my-free-trial-what-is-excluded). +More than one project access token is only available in paid subscriptions. In Premium and Ultimate trial subscriptions, only one project access token is included. For more information, see the ["What is included" section of the GitLab Trial FAQ](https://about.gitlab.com/free-trial/#what-is-included-in-my-free-trial-what-is-excluded). diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 1eee4364d95..56873c328fa 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -31,23 +31,23 @@ The filtering options are: ### On an epic -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Epics** (**{epic}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Epics**. 1. Identify your desired epic, and select its title. 1. Go to the **Activity** section. 1. For **Sort or filter**, select **Show all activity**. ### On an issue -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues** and find your issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues** and find your issue. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. ### On a merge request -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index bd935db6f02..9b5469f6cec 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -185,8 +185,8 @@ The following time units are available: In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index bb1609a74e5..481eca5a890 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -23,7 +23,7 @@ To pair the Web IDE with a remote development environment, see [remote developme To open the Web IDE from the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Use the <kbd>.</kbd> keyboard shortcut. You can also open the Web IDE from: @@ -36,13 +36,7 @@ You can also open the Web IDE from: To open the Web IDE from a file or the repository file list: -- In the upper-right corner of the page, select **Open in Web IDE**. - -If **Open in Web IDE** is not visible: - -1. Next to **Edit** or **Gitpod**, select the down arrow (**{chevron-lg-down}**). -1. From the dropdown list, select **Open in Web IDE**. -1. Select **Open in Web IDE**. +- In the upper right, select **Edit > Open in Web IDE**. ### From a merge request @@ -89,17 +83,17 @@ For more information, see the [VS Code documentation](https://code.visualstudio. ## Upload a new file -To upload a new file and add it to the Git repository: +To upload a new file in the Web IDE: -1. In the **Explorer** file tree, navigate to the directory where you want to upload the file. -1. Optional. If the directory does not exist yet, select the directory path where you want to have a new directory and either: - - Right-click on the directory path, and select **New Folder...**. You can create a nested directory path with the `/` separator, for example `parentdir/subdir1/subdir2`. - - In the **Explorer** panel, in the upper-right corner, select the new folder (**{folder-new}**) icon. -1. Enter the name of the new directory, and press <kbd>Enter/Return</kbd> to create it. -1. Right-click on the directory path and select `Upload...`. -1. Select the file you want to upload, then select `Open`. You can select and add multiple files at once. +1. On the activity bar on the left, select **Explorer** and go to the directory where you want to upload the file. +1. Optional. For a new directory, go to the path where you want to have the directory and do one of the following: + - Right-click the path, and select **New Folder...**. You can create a nested path with `/` (for example, `parentdir/subdir1/subdir2`). + - In the upper right of the **Explorer** panel, select **New Folder...** (**{folder-new}**). +1. Enter the name of the new directory, and press <kbd>Enter</kbd>. +1. Right-click the path, and select **Upload...**. +1. Select the file you want to upload, then select **Open**. You can upload multiple files at once. -The file is uploaded and automatically added as a new file to the Git repository. +The new file is uploaded and automatically added to the repository. ## Switch branches @@ -129,7 +123,17 @@ To commit changes in the Web IDE: or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. 1. Enter your commit message. 1. Select **Commit & Push**. -1. Commit to the current branch, or create a new branch. +1. Commit to the current branch, or [create a new branch](#create-a-branch). + +## Create a merge request + +To create a merge request in the Web IDE: + +1. [Commit the changes](#commit-changes). +1. In the pop-up notification in the lower-right corner, select **Create Merge Request**. + A new window opens for you to create the [merge request](../merge_requests/index.md). + +To access missed notifications, see [Access notifications](#access-notifications). ## Use the command palette @@ -178,6 +182,13 @@ To change the Web IDE theme: The active color theme is stored in the [user settings](#edit-settings). +## Access notifications + +When you perform actions in the Web IDE, notifications appear in the lower-right corner. To access missed notifications: + +1. On the status bar, in the lower-right corner, select the bell (**{notifications}**) for a list of notifications. +1. Select the notification you want to access. + <!-- ## Privacy and data collection for extensions The Web IDE Extension Marketplace is based on Open VSX. Open VSX does not collect any @@ -194,6 +205,9 @@ To protect your privacy and data: ## Interactive web terminals for the Web IDE (Beta) +WARNING: +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. + When you set up a remote development server in the Web IDE, you can use interactive web terminals to: - Access a remote shell on the server. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 9327ce53b3f..2271c33b5b4 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -27,10 +27,10 @@ can edit group wikis. Group wiki repositories can be moved using the To access a group wiki: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. To display the wiki, either: - - On the left sidebar, select **Wiki**. - - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + - On the left sidebar, select **Plan > Wiki**. + - On any page in the group, use the <kbd>g</kbd> + <kbd>w</kbd> [wiki keyboard shortcut](../../shortcuts.md). ## Export a group wiki @@ -67,8 +67,8 @@ can enable or disable a group wiki through the group settings. To open group settings: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: - **Enabled**: For public groups, everyone can access the wiki. For internal groups, only authenticated users can access the wiki. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index eb13814f2ad..0d3782cfd09 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -31,9 +31,9 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se To access a project wiki: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. To display the wiki, either: - - On the left sidebar, select **Wiki**. + - On the left sidebar, select **Plan > Wiki**. - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> [wiki keyboard shortcut](../../shortcuts.md). @@ -61,10 +61,8 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Select **Create your first page**. 1. GitLab requires this first page be titled `home`. The page with this title serves as the front page for your wiki. @@ -79,10 +77,8 @@ to be used as your wiki's home page. To create it: Users with at least the Developer role can create new wiki pages: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. 1. Add a title for your new page. Page titles use @@ -142,10 +138,8 @@ may not be able to check out the wiki locally afterward. You need at least the Developer role to edit a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to edit, and either: - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). - Select the edit icon (**{pencil}**). @@ -163,10 +157,8 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the Developer role to delete a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to delete. 1. Select the edit icon (**{pencil}**). 1. Select **Delete page**. @@ -176,10 +168,8 @@ You need at least the Developer role to delete a wiki page: You need at least the Developer role to move a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. For example, if you have a wiki page @@ -202,10 +192,8 @@ The history page shows: To view the changes for a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to view history for. 1. Select **Page history**. @@ -215,10 +203,8 @@ To view the changes for a wiki page: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in. @@ -248,10 +234,8 @@ You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -284,11 +268,11 @@ You can disable group wikis from the [group settings](group.md#configure-group-w To add a link to an external wiki from a project's left sidebar: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Add the URL to your external wiki. -1. Optional. To verify the connection, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. You can now see the **External wiki** option from your project's @@ -300,8 +284,8 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +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. Select **Save changes**. @@ -310,8 +294,8 @@ To hide the link to an external wiki: To disable a project's internal wiki: -1. On the top bar, select **Main menu > Projects** and find your project. -1. Go to your project and select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). 1. Select **Save changes**. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 69087791a3e..5bd7c12ed31 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -11,9 +11,15 @@ code are saved in projects, and most features are in the scope of projects. ## View projects -To view all your projects, on the top bar, select **Main menu > Projects > View all projects**. +To view all your projects: -To browse all public projects, select **Main menu > Explore > Projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. + +To browse all projects you can access: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Explore**. ### Who can view the Projects page @@ -42,11 +48,12 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec To explore project topics: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. Select the **Explore topics** tab. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Explore**. +1. On the left sidebar, select **Topics**. 1. To view projects associated with a topic, select a topic. -The **Explore topics** tab shows a list of topics sorted by the number of associated projects. +The **Explore topics** page shows a list of topics, sorted by the number of associated projects. You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). @@ -59,13 +66,14 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. In the upper-right corner of the page, select **Star**. ## View starred projects -1. On the top bar, select **Main menu > Projects > View all projects**. -1. Select the **Starred projects** tab. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. +1. Select the **Starred** tab. 1. GitLab displays information about your starred projects, including: - Project description, including name, description, and icon. @@ -83,17 +91,20 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: -1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. In the **Yours** tab, select **Personal**. ## Delete a project -After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group -you can [enable delayed project removal](../group/manage.md#enable-delayed-project-deletion). +After you delete a project: + +- Projects in personal namespaces are deleted immediately. +- Projects in groups are [deleted after a retention period](../project/settings/index.md#delayed-project-deletion). To delete a project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. @@ -107,12 +118,10 @@ To delete a project: > - [Available to all users](https://gitlab.com/gitlab-org/gitlab/-/issues/346976) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) in GitLab 14.9. [Feature flag `project_owners_list_project_pending_deletion`](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) removed. -When delayed project deletion is [enabled for a group](../group/manage.md#enable-delayed-project-deletion), -projects within that group are not deleted immediately, but only after a delay. - To view a list of all projects that are pending deletion: -1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. Based on your GitLab version: - GitLab 14.6 and later: select the **Pending deletion** tab. - GitLab 14.5 and earlier: select the **Deleted projects** tab. @@ -127,18 +136,14 @@ Each project in the list shows: To view the activity of a project: -1. On the top bar, select **Main menu > Projects** and find your project.. -1. On the left sidebar, select **Project information > Activity**. +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. ## Search in projects -You can search through your projects. - -1. On the top bar, select **Main menu**. -1. In **Search your projects**, type the project name. - -GitLab filters as you type. +To search through your projects, on the left sidebar, at the top, select **Search GitLab** +(**{search}**). GitLab filters as you type. You can also look for the projects you [starred](#star-a-project) (**Starred projects**). @@ -161,7 +166,10 @@ You can also choose to hide or show archived projects. You can filter projects by the programming language they use. To do this: -1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select either: + - **View all your projects**, to filter your projects. + - **Explore**, to filter all projects you can access. 1. From the **Language** dropdown list, select the language you want to filter projects by. A list of projects that use the selected language is displayed. @@ -174,8 +182,8 @@ Prerequisite: - You must have the Owner role for the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggle by each feature you want to turn on or off, or change access for. 1. Select **Save changes**. @@ -190,7 +198,7 @@ When you leave a project: To leave a project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a [group namespace](../namespace/index.md). diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 58eebc16d74..002cb97dd93 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -59,7 +59,7 @@ Prerequisite: - You must have the Owner role for a project. -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. @@ -78,7 +78,7 @@ Prerequisites: restrictive as the new setting of the parent group. For example, you cannot set a group to private if a subgroup or project in that group is public. -1. On the top bar, select **Main menu > Groups** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Naming, visibility**. 1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index 63d7f18f70c..5b302d976dd 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -40,6 +40,8 @@ To restore a namespace to its standard state, you can: | CI/CD | Create, edit, admin, and run pipelines <br> Create, edit, admin, and run builds <br> Create and edit admin environments <br> Create and edit admin deployments <br> Create and edit admin clusters <br> Create and edit admin releases | | Namespaces | **For exceeded free user limits:** Invite new users | +When you try to execute a restricted action in a read-only namespace, you might get a `404` error. + ## Related topics - [Frequently Asked Questions - GitLab SaaS Free Tier](https://about.gitlab.com/pricing/faq-efficient-free-tier/) diff --git a/doc/user/search/index.md b/doc/user/search/index.md index f6733abd305..2278da9a714 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -64,8 +64,8 @@ search, or choose a specific group or project. To search through code or other documents in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the top bar, in the search field, type the string you want to search for. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and type the string you want to search for. 1. Press **Enter**. Code search shows only the first result in the file. @@ -96,8 +96,6 @@ To filter code search results by one or more languages: ## Search for projects by full path > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/388473) on GitLab.com in GitLab 15.9. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111808) on self-managed GitLab 15.10. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. You can search for a project by entering its full path (including the namespace it belongs to) in the search box. @@ -108,12 +106,24 @@ For example, the search query: - `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. - `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. +### Exclude archived projects from project search results + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. On GitLab.com, this feature is not available. + +Archived projects are included in project search results by default. To exclude archived projects, ensure the `search_projects_hide_archived` flag is enabled. + +To include archived projects with `search_projects_hide_archived` enabled, you must add the parameter `include_archived=true` to the URL. + ## Search for a SHA You can search for a commit SHA. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the top bar, in the search field, type the SHA. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and type the SHA. If a single result is returned, GitLab redirects to the commit result and gives you the option to return to the search results page. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 3b6c6105315..e195be5586a 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -310,18 +310,6 @@ These shortcuts are available when viewing [epics](group/epics/index.md): | <kbd>e</kbd> | Edit description. | | <kbd>l</kbd> | Change label. | -## Metrics - -These shortcuts are available when using metrics: - -| Keyboard shortcut | Description | -|-------------------|---------------------| -| <kbd>e</kbd> | Expand panel. | -| <kbd>l</kbd> | View logs. | -| <kbd>d</kbd> | Download CSV. | -| <kbd>c</kbd> | Copy link to chart. | -| <kbd>a</kbd> | Alerts. | - ## Disable keyboard shortcuts > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22113) in GitLab 12.8. @@ -336,7 +324,7 @@ press <kbd>?</kbd> to display the list of shortcuts. To enable keyboard shortcuts: -1. On the top bar, select the Help menu (**{question}**), then **Keyboard shortcuts**. +1. On the left sidebar, at the bottom, select **Help** (**{question}**), then **Keyboard shortcuts**. 1. Select **Toggle shortcuts**. ## Troubleshooting diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 7ca897288e1..3ad003e4f4c 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -66,14 +66,22 @@ In GitLab versions 13.0 and later, snippets are [versioned by default](#versione To discover all snippets visible to you in GitLab, you can: -- **View all snippets visible to you**: On the top bar of your GitLab - instance, select **Main menu > Your work** and then **Snippets** to view your snippets dashboard. -- **Visit [GitLab snippets](https://gitlab.com/dashboard/snippets)** for your snippets on GitLab.com. -- **Explore all public snippets**: On the top bar of your GitLab - instance, select **Main menu > Explore** and select **Snippets** to view - [all public snippets](https://gitlab.com/explore/snippets). -- **View a project's snippets**: In your project, - go to **Snippets**. +- **View a project's snippets**: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Snippets**. +- **View all the snippets you created**: + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Your work**. + 1. Select **Snippets**. + + On GitLab.com, you can also visit your [snippets directly](https://gitlab.com/dashboard/snippets). + +- **Explore all public snippets**: + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Explore**. + 1. Select **Snippets**. + + On GitLab.com, you can also visit [all public snippets directly](https://gitlab.com/explore/snippets). ## Change default visibility of snippets @@ -225,8 +233,8 @@ Prerequisites: To do this task: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Snippets**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Code > Snippets**. 1. Select the snippet you want to report as spam. 1. Select **Submit as spam**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index b698f5a3edc..a11f3c4dbd6 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -277,7 +277,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten - Use an existing SSH in your 1Password vault to authenticate with GitLab. 1. Sign in to GitLab. -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. 1. Select **Key**, and you should see the 1Password helper appear. @@ -322,7 +322,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA. 1. Sign in to GitLab. -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. 1. In the **Key** box, paste the contents of your public key. @@ -395,7 +395,7 @@ on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`. ## View your account's SSH keys 1. Sign in to GitLab. -1. On the top bar, in the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **SSH Keys**. diff --git a/doc/user/tasks.md b/doc/user/tasks.md index fc232ee298e..b14f4acca36 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -130,6 +130,16 @@ To edit the description of a task: 1. Above the text box, select **Rich text**. 1. Make your changes, and select **Save**. +## Promote a task to an issue + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To promote a task to an issue, use the `/promote_to issue` [quick action](../user/project/quick_actions.md). + ## Remove a task from an issue Prerequisites: @@ -316,3 +326,36 @@ You can also filter activity by **Comments only** and **History only** in additi ## Comments and threads You can add [comments](discussions/index.md) and reply to threads in tasks. + +## Copy task reference + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1. + +To refer to a task elsewhere in GitLab, you can use its full URL or a short reference, which looks like +`namespace/project-name#123`, where `namespace` is either a group or a username. + +To copy the task reference to your clipboard: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your task to view it. +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. + +You can now paste the reference into another description or comment. + +For more information about task references, see [GitLab-Flavored Markdown](markdown.md#gitlab-specific-references). + +## Copy task email address + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396553) in GitLab 16.1. + +You can create a comment in a task by sending an email. +Sending an email to this address creates a comment that contains the email body. + +For more information about creating comments by sending an email and the necessary configuration, see +[Reply to a comment by sending email](discussions/index.md#reply-to-a-comment-by-sending-email). + +To copy the task's email address: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy task email address**. diff --git a/doc/user/todos.md b/doc/user/todos.md index 8f67311b559..95bc8a553c1 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -20,7 +20,7 @@ You can use the To-Do List to track [actions](#actions-that-create-to-do-items) To access your To-Do List: -On the top bar, in the upper-right corner, select the To-Do List (**{task-done}**). +On the left sidebar, at the top, select To-Do list (**{task-done}**). ## Search the To-Do List diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 822f169c2a3..5c6c64a3485 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -23,10 +23,8 @@ Prerequisites: - To view storage usage for a project, you must have at least the Maintainer role for the project or Owner role for the namespace. - To view storage usage for a namespace, you must have the Owner role for the namespace. -1. Go to your project or namespace: - - For a project, on the top bar, select **Main menu > Projects** and find your project. - - For a namespace, enter the URL in your browser's toolbar. -1. From the left sidebar, select **Settings > Usage Quotas**. +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. Select any title to view details. The information on this page @@ -42,6 +40,54 @@ Container Registry usage is available only for GitLab.com. This feature requires of the GitLab Container Registry. To learn about the proposed release for self-managed installations, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). +#### How container registry usage is calculated + +Image layers stored in the Container Registry are deduplicated at the root namespace level. + +An image is only counted once if: + +- You tag the same image more than once in the same repository. +- You tag the same image across distinct repositories under the same root namespace. + +An image layer is only counted once if: + +- You share the image layer across multiple images in the same container repository, project, or group. +- You share the image layer across different repositories. + +Only layers that are referenced by tagged images are accounted for. Untagged images and any layers +referenced exclusively by them are subject to [online garbage collection](packages/container_registry/delete_container_registry_images.md#garbage-collection). +Untagged image layers are automatically deleted after 24 hours if they remain unreferenced during that period. + +Image layers are stored on the storage backend in the original (usually compressed) format. This +means that the measured size for any given image layer should match the size displayed on the +corresponding [image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md#example-image-manifest). + +Namespace usage is refreshed a few minutes after a tag is pushed or deleted from any container repository under the namespace. + +#### Delayed refresh + +It is not possible to calculate [container registry usage](#container-registry-usage) +with maximum precision in real time for extremely large namespaces (about 1% of namespaces). +To enable maintainers of these namespaces to see their usage, there is a delayed fallback mechanism. +See [epic 9413](https://gitlab.com/groups/gitlab-org/-/epics/9413) for more details. + +If the usage for a namespace cannot be calculated with precision, GitLab falls back to the delayed method. +In the delayed method, the displayed usage size is the sum of **all** unique image layers +in the namespace. Untagged image layers are not ignored. As a result, +the displayed usage size might not change significantly after deleting tags. Instead, +the size value only changes when: + +- An automated [garbage collection process](packages/container_registry/delete_container_registry_images.md#garbage-collection) + runs and deletes untagged image layers. After a user deletes a tag, a garbage collection run + is scheduled to start 24 hours later. During that run, images that were previously tagged + are analyzed and their layers deleted if not referenced by any other tagged image. + If any layers are deleted, the namespace usage is updated. +- The namespace's registry usage shrinks enough that GitLab can measure it with maximum precision. + As usage for namespaces shrinks to be under the [limits](#namespace-storage-limit), + the measurement switches automatically from delayed to precise usage measurement. + There is no place in the UI to determine which measurement method is being used, + but [issue 386468](https://gitlab.com/gitlab-org/gitlab/-/issues/386468) proposes to improve this. + ### Storage usage statistics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68898) project-level graph in GitLab 14.4 [with a flag](../administration/feature_flags.md) named `project_storage_ui`. Disabled by default. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 922ce8e1354..eb3ce1c5aff 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -13,7 +13,7 @@ FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `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/alpha-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. @@ -23,33 +23,36 @@ Each workspace includes its own set of dependencies, libraries, and tools, which ### Prerequisites -- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. See the [supported Kubernetes versions](../clusters/agent/index.md#gitlab-agent-for-kubernetes-supported-cluster-versions). +- 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: +- 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" - ``` + ```yaml + remote_development: + enabled: true + dns_zone: "workspaces.example.dev" + ``` - Update `dns_zone` as needed. - -- In each public project you want to use this feature for, define a [devfile](#devfile). Ensure the container images used in the devfile support [arbitrary user IDs](#arbitrary-user-ids). + 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). ### Create a workspace -To create a workspace in GitLab: +To create a workspace: -1. On the top bar, select **Main menu > Projects** and find your project. -1. In the root directory of your project, create a file named `.devfile.yaml`. -1. On the left sidebar, select **Workspaces**. -1. In the upper right, select **New workspace**. -1. From the **Select project** dropdown list, select a project with a `.devfile.yaml` file. You can only create workspaces for public projects. +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**. @@ -84,9 +87,9 @@ Only these properties are relevant to the GitLab implementation of the `containe | `endpoints` | Port mappings to expose from the container. | | `volumeMounts` | Storage volume to mount in the container. | -### Example definition +### Example configurations -The following is an example devfile: +The following is an example devfile configuration: ```yaml schemaVersion: 2.2.0 @@ -153,6 +156,6 @@ If you already have running workspaces, an administrator must manually delete th ## 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 the container. CRI-O, the container runtime interface used by Kubernetes, has a default group ID of `0` for all containers. +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). |