diff options
Diffstat (limited to 'doc/user/project')
160 files changed, 3887 insertions, 3157 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index c275d2b39db..39c1d228d63 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -130,7 +130,7 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Badges**. 1. Select **Add badge**. @@ -152,7 +152,7 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter _Pipeline Status_. @@ -181,7 +181,7 @@ If you need individual badges for each project, either: To add a new badge to a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under @@ -203,7 +203,7 @@ Badges associated with a group can be edited or deleted only at the [group level You can view the exact link for your badges. Then you can use the link to embed the badge in your HTML or Markdown pages. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. @@ -270,7 +270,7 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge with a custom image to a group or project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > General**. 1. Expand **Badges**. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 45d3834542b..d8b1b6fd413 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -56,7 +56,7 @@ cluster certificates: 1. Go to your: - Project's **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Main menu > Admin > Kubernetes**, for an instance-level cluster. + - The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -248,7 +248,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Amazon EKS**. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 5127248baed..7e2c429c6bb 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -68,7 +68,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Main menu > Admin > Kubernetes** page, for an instance-level cluster. + 1. The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown list. 1. On the **Connect a cluster** page, fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a3a7cb35346..a087460d89e 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -63,7 +63,7 @@ cluster certificates: - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. + - The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Google GKE**. 1. Connect your Google account if you haven't done already by selecting the diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 16ad95bb95c..a3263109bb1 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -19,7 +19,7 @@ When you successfully connect an existing cluster using cluster certificates, th 1. Go to your: - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. + - The Admin Area's **Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). 1. Select **Save changes**. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 58553fbb1c3..1a69b45b651 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -24,5 +24,5 @@ to a single project. To view project-level Kubernetes clusters: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index 74974958910..d783471f0da 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -6,17 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Code Owners **(PREMIUM ALL)** -> Moved to GitLab Premium in 13.9. - Use the Code Owners feature to define who has expertise for specific parts of your project's codebase. Define the owners of files and directories in a repository to: - **Require owners to approve changes.** Combine protected branches with Code Owners to require experts to approve merge requests before they merge into a protected branch. - **Identify owners.** Code Owner names are displayed on the files and directories they own: +  -Use Code Owners in combination with merge request +Combine Code Owners with merge request [approval rules](../merge_requests/approvals/rules.md) (either optional or required) to build a flexible approval workflow: @@ -42,13 +41,11 @@ For example: <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> </figure> -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - ## View Code Owners of a file or directory To view the Code Owners of a file or directory: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Go to the file or directory you want to see the Code Owners for. 1. Optional. Select a branch or tag. @@ -57,14 +54,14 @@ GitLab shows the Code Owners at the top of the page. ## Set up Code Owners -1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file). +1. Create a `CODEOWNERS` file in your [preferred location](#codeowners-file). 1. Define some rules in the file following the [Code Owners syntax reference](reference.md). Some suggestions: - Configure [All eligible approvers](../merge_requests/approvals/rules.md#code-owners-as-eligible-approvers) approval rule. - [Require Code Owner approval](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) on a protected branch. 1. Commit your changes, and push them up to GitLab. -### Code Owners file +### `CODEOWNERS` file A `CODEOWNERS` file (with no extension) specifies the users or [shared groups](../members/share_project_with_groups.md) responsible for @@ -78,9 +75,17 @@ all others are ignored: 1. In the `docs` directory: `./docs/CODEOWNERS`. 1. In the `.gitlab` directory: `./.gitlab/CODEOWNERS`. -### Add a group as a Code Owner +For more information, see [Code Owners syntax and error handling](reference.md). + +#### When user or group change names + +When a user or group change their names, the `CODEOWNERS` isn't automatically updated with the new names. +To enter the new names, you must edit the file. -> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. +Organizations using SAML SSO can [set usernames](../../../integration/saml.md#set-a-username) to +prevent users from being able to change their usernames. + +### Add a group as a Code Owner To set the members of a group or subgroup as a Code Owner: @@ -99,8 +104,6 @@ file.md @group-x @group-x/subgroup-y #### Group inheritance and eligibility -> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. - ```mermaid graph TD A[Parent group X] -->|owns| B[Project A] @@ -188,9 +191,6 @@ Only one CODEOWNERS pattern per section is matched to a file path. ### Organize Code Owners by putting them into sections -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed. - You can organize Code Owners by putting them into named sections. You can use sections for shared directories, so that multiple @@ -215,9 +215,10 @@ The following image shows a **Groups** and **Documentation** section: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `codeowners_default_owners`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115888) in GitLab 15.11. Feature flag `codeowners_default_owners` removed. -If multiple file paths inside a section share the same ownership, define a default -Code Owner for the section. All paths in that section inherit this default, unless -you override the section default on a specific line. +If multiple file paths inside a section share the same ownership, define default +Code Owners for the section. +All paths in that section inherit this default, unless you override the section +default on a specific line. Default owners are applied when specific owners are not specified for file paths. Specific owners defined beside the file path override default owners: @@ -227,7 +228,7 @@ Specific owners defined beside the file path override default owners: docs/ README.md -[Database] @database-team +[Database] @database-team @agarcia model/db/ config/db/database-setup.md @docs-team ``` @@ -235,9 +236,14 @@ config/db/database-setup.md @docs-team In this example: - `@docs-team` owns all items in the `Documentation` section. -- `@database-team` owns all items in the `Database` section except +- `@database-team` and `@agarcia` own all items in the `Database` section except `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. +Compare this behavior to when you use [regular entries and sections together](#use-regular-entries-and-sections-together), +when entries in sections don't override entries without sections. + +#### Use default owners and optional sections together + To combine the syntax for default owners with [optional sections](#make-a-code-owners-section-optional) and required approvals, place default owners at the end: @@ -251,6 +257,38 @@ model/db/ config/db/database-setup.md @docs-team ``` +#### Use regular entries and sections together + +If you set a default Code Owner for a path outside a section, their approval is always required, and +the entry isn't overridden. +Entries without sections are treated as if they were another, unnamed section: + +```plaintext +# Required for all files +* @general-approvers + +[Documentation] @docs-team +docs/ +README.md +*.txt + +[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +In this example: + +- `@general-approvers` owns all items everywhere, without overrides. +- `@docs-team` owns all items in the `Documentation` section. +- `@database-team` owns all items in the `Database` section except + `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. +- A merge request that modifies `model/db/CHANGELOG.txt` would require three approvals: one from each + of the `@general-approvers`,`@docs-team`, and `@database-team` groups. + +Compare this behavior to when you use only [default owners for sections](#set-default-owner-for-a-section), +when specific entries within a section override the section default. + #### Sections with duplicate names If multiple sections have the same name, they are combined. @@ -275,8 +313,6 @@ entries under **Database**. The entries defined under the sections **Documentati #### Make a Code Owners section optional -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. - You can designate optional sections in your Code Owners file. Prepend the section name with the caret `^` character to treat the entire section as optional. Optional sections enable you to designate responsible parties for various parts @@ -314,14 +350,14 @@ section is marked as optional. You can require multiple approvals for the Code Owners sections under the Approval Rules area in merge requests. Append the section name with a number `n` in brackets. This requires `n` approvals from the Code Owners in this section. -Please note valid entries for `n` are integers `≥ 1`. `[1]` is optional as it is the default. Invalid values for `n` are treated as `1`. +Valid entries for `n` are integers `≥ 1`. `[1]` is optional because it is the default. Invalid values for `n` are treated as `1`. WARNING: [Issue #384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes to the behavior of this setting. Do not intentionally set invalid values. They may become valid in the future, and cause unexpected behavior. -Please confirm you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals will be optional. +Make sure you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals are optional. In this example, the `[Documentation]` section requires 2 approvals: @@ -337,7 +373,7 @@ The `Documentation` Code Owners section under the **Approval Rules** area displa  -### Allowed to Push +### Allowed to push Users who are **Allowed to push** can choose to create a merge request for their changes, or push the changes directly to a branch. If the user @@ -350,12 +386,15 @@ and release tooling. All changes from users _without_ the **Allowed to push** permission must be routed through a merge request. -## Technical Resources +## Related topics -[Code Owners development guidelines](../../../development/code_owners/index.md) +- [Syntax reference](reference.md) +- [Development guidelines](../../../development/code_owners/index.md) ## Troubleshooting +When working with Code Owners, you might encounter the following issues. + For more information about how the Code Owners feature handles errors, see the [Code Owners reference](reference.md). @@ -363,7 +402,8 @@ For more information about how the Code Owners feature handles errors, see the A Code Owner approval rule is optional if any of these conditions are true: -- The user or group are not a member of the project. Code Owners [cannot inherit from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). +- The user or group is not a member of the project. + Code Owners [cannot inherit members from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). - [Code Owner approval on a protected branch](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. - The section is [marked as optional](#make-a-code-owners-section-optional). @@ -383,7 +423,15 @@ if any of these conditions are true: member of the Code Owner group. - Current user is an external user who does not have permission to the internal Code Owner group. -### Approval rule is invalid. GitLab has approved this rule automatically to unblock the merge request +### Approval rule is invalid + +You might get an error that states: + +```plaintext +Approval rule is invalid. +GitLab has approved this rule automatically to unblock the merge request. +``` + +This issue occurs when an approval rule uses a Code Owner that is not a direct member of the project. -This message may appear if an approval rule uses a Code Owner that is not a direct member of the project. -Check that the group or user has been invited to the project. +The workaround is to check that the group or user has been invited to the project. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 395873d3107..91a3d71642d 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -21,7 +21,7 @@ type: howto, reference WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493) -to add this functionality to the [agent](../index.md). +to add this functionality to the [agent](../clusters/agent/index.md). FLAG: On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index f0d84616c24..c0a50dade31 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -64,7 +64,7 @@ Deploy keys work even if the user who created them is removed from the group or To view the deploy keys available to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. @@ -82,7 +82,7 @@ Prerequisites: - [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Add new key**. @@ -104,7 +104,7 @@ Prerequisites: To create a public deploy key: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Deploy Keys**. 1. Select **New deploy key**. @@ -122,7 +122,7 @@ Prerequisites: To grant a public deploy key access to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Publicly accessible deploy keys**. @@ -139,7 +139,7 @@ Prerequisites: To edit the project access permissions of a deploy key: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. In the key's row, select **Edit** (**{pencil}**). @@ -156,7 +156,7 @@ Prerequisites: To disable a deploy key: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). @@ -192,7 +192,7 @@ If you need to find the keys that belong to a non-member or blocked user, you can use [the Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) to identify unusable deploy keys using a script similar to the following: ```ruby -ghost_user_id = User.ghost.id +ghost_user_id = Users::Internal.ghost.id DeployKeysProject.with_write_access.find_each do |deploy_key_mapping| project = deploy_key_mapping.project diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 41fb0018be9..8b7e185508b 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy tokens **(FREE ALL)** -> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. - You can use a deploy token to enable authentication of deployment tasks, independent of a user account. In most cases you use a deploy token from an external host, like a build server or CI/CD server. @@ -92,7 +90,7 @@ Prerequisites: - You must have at least the Maintainer role for the project or group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. Select **Add token**. @@ -112,7 +110,7 @@ Prerequisites: To revoke a deploy token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4da49c4fb12..97b350c8692 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -16,7 +16,7 @@ You might want to use these templates: - For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - For every issue or merge request for a specific project, so the layout is consistent. -- For a [Service Desk email template](service_desk/index.md#use-a-custom-template-for-service-desk-tickets). +- For a [Service Desk email template](service_desk/configure.md#use-a-custom-template-for-service-desk-tickets). For description templates to work, they must be: @@ -32,7 +32,7 @@ directory in your repository. To create an issue description template: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -52,7 +52,7 @@ that depend on the contents of commit messages and branch names. To create a merge request description template for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -110,7 +110,7 @@ You can set a description template at the **instance level** for issues and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md). You can also use the instance template repository for file templates. -You might also be interested [project templates](../admin_area/custom_project_templates.md) +You might also be interested in [project templates](../admin_area/custom_project_templates.md) that you can use when creating a new project in the instance. ### Set group-level description templates **(PREMIUM ALL)** @@ -118,13 +118,18 @@ that you can use when creating a new project in the instance. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. -With **group-level** description templates, you can select a repository within the group to store -your templates. Then, you can access these templates from other projects in the group. +With **group-level** description templates, you can select a project within the group to store +your templates. Then, you can access these templates in other projects in the group. As a result, you can use the same templates in issues and merge requests in all the group's projects. +Prerequisites: + +- You must have the Owner role for the group. +- The project must be a direct child of the group. + To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Templates**. 1. From the dropdown list, select your template project as the template repository at group level. @@ -155,7 +160,7 @@ To set a default description template for merge requests, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. @@ -167,7 +172,7 @@ To set a default description template for issues, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Default description template for issues**. 1. Fill in the text area. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 88aa9446787..783f5f3ee7c 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -151,7 +151,7 @@ You can push files to GitLab whether they're locked or unlocked. NOTE: Although multi-branch file locks can be created and managed through the Git LFS -command line interface, file locks can be created for any file. +command-line interface, file locks can be created for any file. ### View exclusively-locked files @@ -221,7 +221,7 @@ similar functionality for locked files is discussed in To view and remove file locks: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Locked files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 0f612d5b222..bafcbbb9cbd 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -36,7 +36,7 @@ When importing: - [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. -- [Bitbucket Cloud import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your +- [Bitbucket Cloud import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -117,5 +117,5 @@ current Bitbucket public name, and reconnect if there's a mismatch: 1. Following reconnection, the user should use the API again to verify that their `extern_uid` in the GitLab database now matches their current Bitbucket public name. -The importer must then [delete the imported project](../../project/working_with_projects.md#delete-a-project) +The importer must then [delete the imported project](../../project/settings/index.md#delete-a-project) and import again. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index a80ce95c163..4afe23a29fa 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -32,7 +32,7 @@ You can import Bitbucket repositories to GitLab. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [Bitbucket Server import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Bitbucket Server import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -87,6 +87,9 @@ original creator. The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the repository imports under the namespace of the user who started the import process. +The importer attempts to find reviewers by their email address in the GitLab user database. If they don't exist in GitLab, they cannot be added as reviewers to a +merge request. + ### User assignment by username > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default. diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index f5f924ef603..90ed6cfdb2c 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -39,10 +39,10 @@ The following list illustrates the main differences between CVS and Git: your state in version control, then you merge the other developer's changes. You can also ask the other developer to do the merge and resolve any conflicts themselves. -- **Signed commits.** Git supports signing your commits with GPG for additional +- **Signed commits.** Git supports + [signing your commits](../repository/signed_commits/index.md) for additional security and verification that the commit indeed came from its original author. - GitLab can [integrate with GPG](../repository/gpg_signed_commits/index.md) - and show whether a signed commit is correctly verified. + GitLab shows whether a signed commit is correctly verified. _Some of the items above were taken from this great [Stack Overflow post](https://stackoverflow.com/a/824241/974710). For a more diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 85c24886687..2bce6708556 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -19,7 +19,7 @@ users. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [FogBugz import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [FogBugz import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The FogBugz import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 98457b96dde..9629ec03443 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -32,7 +32,7 @@ on the issue about the original Gitea author. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. - Gitea version 1.0.0 or later. -- [Gitea import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Gitea import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Gitea import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 2079c61da31..75d25e29bd9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -28,6 +28,9 @@ When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and assignee. The project creator is usually the user that initiated the import process. A note on the issue mentioning the original GitHub author is added. +- Reviewers assigned to GitHub pull requests that do not exist in GitLab are not imported. In this case, the import + creates comments describing that non-existent users were added as reviewers and approvers. However, the actual + reviewer status and approval are not applied to the merge request in GitLab. - You can change the target namespace and target repository name before you import. - The importer also imports branches on forks of projects related to open pull requests. These branches are imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to @@ -43,7 +46,7 @@ For an overview of the import process, see [How to migrate from GitHub to GitLab To import projects from GitHub: -- [GitHub import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [GitHub import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The GitHub import source is enabled by default on GitLab.com. - You must have at least the Maintainer role on the destination group to import to. @@ -55,12 +58,8 @@ To import projects from GitHub: When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. For the importer to succeed, matching email addresses are required. -- GitHub accounts must have a GitHub public-facing email address is populated. This means all comments and contributions - are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you - may have to add it on existing accounts. - -Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an OmniAuth provider, ensure that the URL -perimeter is specified in the [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). +- GitHub accounts must have a GitHub public-facing email address so that all comments and contributions can be properly mapped to + the same user in GitLab. GitHub Enterprise does not require this field to be populated so you might have to add it on existing accounts. ### Importing from GitHub Enterprise to self-managed GitLab @@ -68,7 +67,7 @@ If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable the [GitHub integration](../../../integration/github.md). - GitHub must be enabled as an import source in the - [Admin Area](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [Admin Area](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources). - For GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). @@ -78,7 +77,17 @@ If you are importing from GitHub.com to a self-managed GitLab instance: - You don't need to enable the [GitHub integration](../../../integration/github.md). - GitHub must be enabled as an import source in the - [Admin Area](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [Admin Area](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources). + +### Known issues + +- GitHub pull request comments (known as diff notes in GitLab) created before 2017 are imported in separate threads. + This occurs because of a limitation of the GitHub API that doesn't include `in_reply_to_id` for comments before 2017. +- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an + OmniAuth provider, ensure that the URL perimeter is specified in the + [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). +- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424400), Markdown attachments from + repositories on GitHub Enterprise Server instances aren't imported. ## Import your GitHub repository into GitLab @@ -288,10 +297,10 @@ When they are imported, supported GitHub branch protection rules are mapped to e | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | | **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | | **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | -| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | +| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM ALL)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | | **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | -| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | +| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM ALL)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) **(PREMIUM ALL)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index c1d6f5dbcbe..df831c2f3eb 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -41,7 +41,7 @@ with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate gro GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 433496ba6c9..aaf19439c24 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -19,7 +19,7 @@ repositories like the Android Open Source Project (AOSP). > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [Manifest import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Manifest import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Manifest import source is enabled by default on GitLab.com. - GitLab must use PostgreSQL for its database, because [subgroups](../../group/subgroups/index.md) are needed for the manifest import diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md deleted file mode 100644 index 7b9615b883c..00000000000 --- a/doc/user/project/import/phabricator.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -stage: Manage -group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' ---- - -# Import Phabricator tasks into a GitLab project (removed) **(FREE SELF)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106369) in GitLab 15.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/117649) in 16.0. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5d23ee885bb..375cb718538 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -12,15 +12,15 @@ You can import your existing repositories by providing the Git URL. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [Repository by URL import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Repository by URL import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Repository by URL import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. ## Import project by URL -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 478e9c6bf1b..b60d87adbd3 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -134,7 +134,7 @@ Prerequisites: [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. On the left sidebar, select **Search or go to** and find your group. 1. In the upper-right corner, confirm that **New project** is visible. Contact your GitLab administrator if you require permission. diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 60b23540ac3..d8ad7f9a29c 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -24,7 +24,7 @@ Prerequisites: To view project insights: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Insights**. 1. To view a report, select the **Select report** dropdown list. @@ -52,7 +52,7 @@ To configure project insights, either: - Create a `.gitlab/insights.yml` file locally in the root directory of your project, and push your changes. - Create a `.gitlab/insights.yml` file in the UI: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Above the file list, select the branch you want to commit to, select the plus icon, then select **New file**. 1. In the **File name** text box, enter `.gitlab/insights.yml`. 1. In the large text box, update the file contents. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 6005bc48d56..763f478eb99 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -29,7 +29,7 @@ An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.co GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: 1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Apple App Store Connect**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index c73563ba162..442b8695136 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,7 +32,7 @@ In Asana, create a Personal Access Token. Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 9abbe75cc4c..242d5e6974c 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -36,7 +36,7 @@ integration in GitLab. ## Configure GitLab -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 048673cd4a2..febbee66c33 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,7 +14,7 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -39,7 +39,7 @@ project pages. This link takes you to the appropriate Bugzilla project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md index 7075aca28c2..dc93ff8ed06 100644 --- a/doc/user/project/integrations/clickup.md +++ b/doc/user/project/integrations/clickup.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use [ClickUp](https://clickup.com/) as an external issue tracker. To enable the ClickUp integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **ClickUp**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -34,7 +34,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference ClickUp issues in GitLab diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 54d092d2fa9..0a31e66fe96 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -20,7 +20,7 @@ on the left sidebar in your project. To enable a custom issue tracker in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 67f76d48744..29d92b16e32 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -28,7 +28,7 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 105061efba7..5c1130c7893 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -11,7 +11,7 @@ that is pushed to your project. To enable emails on push: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Emails on push**. 1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 7ee0306e7c0..831078e4e4b 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,7 +14,7 @@ This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.n To enable the EWM integration, in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **EWM**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3f4b110468b..c368a9da2f6 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -29,7 +29,7 @@ Complete these steps on GitHub: Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **GitHub**. 1. Ensure the **Active** checkbox is selected. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index a082d9aa5be..d762c71242d 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -30,7 +30,7 @@ Although functionality has not changed, you should [reinstall the app](#update-t To install the GitLab for Slack app from project integration settings: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. Select **Install GitLab for Slack app**. @@ -55,7 +55,7 @@ When GitLab releases new features for the GitLab for Slack app, you might have t To update your GitLab for Slack app: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for +1. On the left sidebar, select **Search or go to** and find a project for which the GitLab for Slack app is configured. 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. @@ -105,7 +105,7 @@ The command returns an error if no matching action is found. By default, slash commands expect a project full path. To create a shorter project alias in the GitLab for Slack app: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. The current **Project Alias**, if any, is displayed. To edit this value, @@ -122,7 +122,7 @@ With Slack notifications, GitLab can send messages to Slack workspace channels f To configure Slack notifications: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for +1. On the left sidebar, select **Search or go to** and find a project for which the GitLab for Slack app is [installed](#install-the-gitlab-for-slack-app). 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. @@ -168,10 +168,19 @@ The following events are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | -| **Group mention in public** | A group is mentioned in a public context. | -| **Group mention in private** | A group is mentioned in a confidential context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in public** | A group is mentioned in a public context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | +### Trigger notifications for group mentions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4. + +To trigger a [notification event](#notification-events) for a group mention, use `@<group_name>` in: + +- Issue and merge request descriptions +- Comments on issues, merge requests, and commits + ## Troubleshooting ### GitLab for Slack app does not appear in the list of integrations diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 696bb6acf99..1affa7abfb4 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -29,7 +29,7 @@ Prerequisites: To enable the Google Play integration in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Google Play**. 1. In **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 803984f82bf..9d6be5da810 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -25,7 +25,7 @@ In the Harbor instance, ensure that: GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Harbor**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 00ae1a0478c..59b5043b8f7 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -18,7 +18,7 @@ Prerequisites: To view the available integrations for your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. You can also view and manage integration settings across [all projects in an instance or group](../../admin_area/settings/project_integration_management.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index f5084392841..146123f97cd 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,7 +39,7 @@ network. For more details, read ## Complete these steps in GitLab -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 9e1de5e3aab..9588fbff922 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -41,7 +41,7 @@ Display name override is not enabled by default, you need to ask your administra After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Mattermost notifications**. 1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 4898d5bd337..715e744988c 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -31,7 +31,7 @@ you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/pla If Mattermost is installed on the same server as GitLab, you can automatically configure Mattermost slash commands: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. 1. Under **Enable integration**, ensure the **Active** checkbox is selected. @@ -67,7 +67,7 @@ To get configuration values from GitLab: 1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index b359696c72b..dea34709dff 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -35,7 +35,7 @@ After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: 1. Sign in to GitLab as an administrator. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Microsoft Teams notifications**. 1. To enable the integration, select **Active**. diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 3697e660deb..cd0a1819afd 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,7 +37,7 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar Complete these steps in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md deleted file mode 100644 index c0b2591d824..00000000000 --- a/doc/user/project/integrations/prometheus.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: 'index.md' ---- - -# Prometheus (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md deleted file mode 100644 index e31f3b26e66..00000000000 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring AWS resources (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md deleted file mode 100644 index 4a0d324932b..00000000000 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring HAProxy (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md deleted file mode 100644 index 49345f41514..00000000000 --- a/doc/user/project/integrations/prometheus_library/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Prometheus Metrics library (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md deleted file mode 100644 index f5bbaffa58e..00000000000 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring Kubernetes (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md deleted file mode 100644 index e38f26710fc..00000000000 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring NGINX (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md deleted file mode 100644 index 189cf59a514..00000000000 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring NGINX Ingress Controller (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md deleted file mode 100644 index e4edd63314f..00000000000 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -remove_date: '2023-08-22' -redirect_to: '../../../../operations/index.md' ---- - -# Monitoring NGINX Ingress Controller with VTS metrics (removed) **(FREE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index 218a036f0a2..3f1907d04cb 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -26,7 +26,7 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. 1. To enable the integration for your instance: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index af2c7265f5d..a66aa9cd00a 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Redmine**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -38,7 +38,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index b2c85c8cb4c..aeddee29109 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -23,7 +23,7 @@ This change is a breaking change. To enable the Shimo integration for your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Shimo**. 1. Under **Enable integration**, ensure the **Active** checkbox is selected. @@ -36,7 +36,7 @@ On the left sidebar, **Shimo** now appears instead of **Wiki**. To view the Shimo Workspace from your group or project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 87d7476e42e..d48fd929d54 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -32,7 +32,7 @@ to control GitLab from Slack. Slash commands are configured separately. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Slack notifications**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -79,10 +79,19 @@ The following triggers are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | -| **Group mention in public** | A group is mentioned in a public context. | -| **Group mention in private** | A group is mentioned in a confidential context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in public** | A group is mentioned in a public context. | +| **[Group mention](#trigger-notifications-for-group-mentions) in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | +## Trigger notifications for group mentions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4. + +To trigger a [notification event](#triggers-for-slack-notifications) for a group mention, use `@<group_name>` in: + +- Issue and merge request descriptions +- Comments on issues, merge requests, and commits + ## Troubleshooting If your Slack integration is not working, start troubleshooting by @@ -147,7 +156,7 @@ Commands that change data can cause damage if not run correctly or under the rig ```ruby # Grab all projects that have the Slack notifications enabled -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Slack' AND s.active = true") +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Integrations::Slack' AND s.active = true") # Disable the integration on each of the projects that were found. p.each do |project| diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 78c8180cb4c..67894e158c8 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -23,7 +23,7 @@ For a list of available slash commands, see [Slash commands](gitlab_slack_applic Slack slash commands are scoped to a project. To configure Slack slash commands: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Slack slash commands** and leave this browser tab open. 1. In a new browser tab, sign in to Slack and [add a new slash command](https://my.slack.com/services/new/slash-commands). diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index ff633783e83..75849d61551 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -26,7 +26,7 @@ are synchronized as requirements in Squash TM and test progress is reported in G ## Configure GitLab -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Squash TM**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index d68222d2f94..4e94ef76f58 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -40,10 +40,10 @@ After you invite the bot to a Telegram channel, you can configure GitLab to send 1. To enable the integration: - **For your group or project:** - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - **For your instance:** - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Telegram**. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index d59bfde5944..34f8cf262cd 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,7 +15,7 @@ copy its URL. In GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 370584303f8..b675ffa7a36 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -26,10 +26,10 @@ notifications: 1. To enable integration: - At the project or group level: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - At the instance level: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select the **Webex Teams** integration. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index c4dd8dcf812..269fdf304a8 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -988,7 +988,7 @@ Payload example: "draft": { "previous": true, "current": false - } + }, "updated_at": { "previous": "2017-09-15 16:50:55 UTC", "current":"2017-09-15 16:52:00 UTC" @@ -1026,7 +1026,7 @@ Payload example: "last_edited_by_id": { "previous": null, "current": 3278533 - }, + } }, "assignees": [ { @@ -1521,7 +1521,8 @@ Deployment events are triggered when a deployment: - Fails - Is cancelled -The `deployable_id` in the payload is the ID of the CI/CD job. +The `deployable_id` and `deployable_url` in the payload represent a CI/CD job that executed the deployment. +When the deployment event occurs by [API](../../../ci/environments/external_deployment_tools.md) or [`trigger` jobs](../../../ci/pipelines/downstream_pipelines.md), `deployable_url` is `null`. Request header: @@ -1879,12 +1880,13 @@ Payload example: ## Emoji events -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.3. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/417288) in GitLab 16.4. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `emoji_webhooks`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can +[disable the feature flag](../../../administration/feature_flags.md) named `emoji_webhooks`. On GitLab.com, this feature is available. NOTE: To have the `emoji_webhooks` flag enabled on GitLab.com, see [issue 417288](https://gitlab.com/gitlab-org/gitlab/-/issues/417288). diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index fe3d5e015a6..8e7f8bcd67d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -40,7 +40,7 @@ including: ## Group webhooks **(PREMIUM ALL)** You can configure a group webhook, which is triggered by events -that occur across all projects in the group. If you configure identical webhooks +that occur across all projects in the group and its subgroups. If you configure identical webhooks in a group and a project, they are both triggered by an event in the project. diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 651c1a15b7a..c05083a1d83 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,7 +14,7 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **YouTrack**. 1. Under **Enable integration**, select the **Active** checkbox. @@ -30,7 +30,7 @@ project pages. This link takes you to the appropriate YouTrack project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 0b8f6cc33fc..60b50251555 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -32,7 +32,7 @@ When you create a confidential issue in a project, the project becomes listed in To create a confidential issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, at the top, select **Create new** (**{plus}**). 1. From the dropdown list, select **New issue**. 1. Complete the [fields](create_issues.md#fields-in-the-new-issue-form). @@ -43,7 +43,7 @@ To create a confidential issue: To change the confidentiality of an existing issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Select the title of your issue to view it. 1. On the right sidebar, next to **Confidentiality**, select **Edit**. diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 3014b088fd6..cd4ef43d333 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -28,7 +28,7 @@ Prerequisites: To create an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Either: - On the left sidebar, select **Plan > Issues**, and then, in the upper-right corner, select **New issue**. @@ -51,7 +51,7 @@ Prerequisites: To create an issue from a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Issues**. 1. In the upper-right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected @@ -98,7 +98,7 @@ Prerequisites: To create an issue from a project issue board: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issue boards**. 1. At the top of a board list, select **Create new issue** (**{plus-square}**). 1. Enter the issue's title. @@ -106,7 +106,7 @@ To create an issue from a project issue board: To create an issue from a group issue board: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Issue boards**. 1. At the top of a board list, select **Create new issue** (**{plus-square}**). 1. Enter the issue's title. @@ -130,7 +130,7 @@ Prerequisites: To email an issue to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. At the bottom of the page, select **Email a new issue to this project**. 1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index b3fe7da4280..882e4d97938 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -76,3 +76,10 @@ you can also [set an issue to close automatically](managing_issues.md#closing-is as soon as the merge request is merged.  + +## From branch names + +When you create a branch in the same project as an issue and start the branch name with the issue +number, followed by a hyphen, the issue and MR you create are linked. +For more information, see +[Prefix branch names with issue numbers](../repository/branches/index.md#prefix-branch-names-with-issue-numbers). diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 86370cab963..34a9b69038b 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,97 +1,102 @@ --- -stage: none -group: unassigned +stage: Plan +group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export issues to CSV **(FREE ALL)** -> Moved to GitLab Free in 12.10. - -You can export issues as CSV files from GitLab, which are sent to your default -notification email address as an attachment. - -**Export Issues to CSV** enables you and your team to export all the data -collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) -file, which stores tabular data in plain text. +You can export issues from GitLab to a plain-text CSV +([comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)) +file. The CSV file is attached to an email, and sent to your default +notification email address. <!-- vale gitlab.Spelling = NO --> -CSV files can be used with any plotter or spreadsheet-based program, such as -Microsoft Excel, Open Office Calc, or Google Sheets. +CSV files can be used with any plotter or spreadsheet-based program, like +Microsoft Excel, OpenOffice Calc, or Google Sheets. Use a CSV list of issues to: <!-- vale gitlab.Spelling = YES --> -Here are some of the uses of exporting issues as CSV files: - -- Make a snapshot of issues for offline analysis or to communicate with other - teams who may not be in GitLab. +- Create a snapshot of issues for offline analysis, or to share with other + teams who might not be in GitLab. - Create diagrams, graphs, and charts from the CSV data. -- Present the data in any other format for auditing or sharing reasons. -- Import the issues elsewhere to a system outside of GitLab. -- Long-term issues' data analysis with multiple snapshots created along the - time. +- Convert the data to other formats for auditing or sharing. +- Import the issues to a system outside of GitLab. +- Analyze long-term trends with multiple snapshots created over time. - Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics. -## Choosing which issues to include - -After selecting a project, from the issues page you can narrow down which -issues to export using the search bar, along with the All/Open/Closed tabs. All -issues returned are exported, including those not shown on the first page. +## Select issues to export - +You can export issues from individual projects, but not groups. -GitLab asks you to confirm the number of issues and email address for the -export, after which the email is prepared. +Prerequisites: - +- You must have at least the Reporter role. -## Sorting +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**. +1. Above the list of issues, select **Search or filter results...**. +1. In the dropdown list that appears, select the attributes to filter by. + For more information about filter options, see + [Filter the list of issues](managing_issues.md#filter-the-list-of-issues). +1. In the upper right, select **Actions** (**{ellipsis_v}**) **> Export as CSV**. +1. In the dialog, verify that the email address is correct, then select **Export issues**. -Exported issues are always sorted by `Title`. +All matching issues are exported, including those not shown on the first page. +The exported CSV does not contain attachments from issues. ## Format -Data is encoded with a comma as the column delimiter, with `"` used to quote -fields if needed, and newlines to separate rows. The first row contains the -headers, which are listed in the following table along with a description of -the values: - -| Column | Description | -|------------------------------------------|-----------------------------------------------------------| -| Title | Issue `title` | -| Description | Issue `description` | -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| State | `Open` or `Closed` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | -| Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| [Epic](../../group/epics/index.md) ID | ID of the parent epic, introduced in 12.7 | -| [Epic](../../group/epics/index.md) Title | Title of the parent epic, introduced in 12.7 | - -In GitLab 14.7 and earlier, the first two columns were `Issue ID` and `URL`, -which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) -when importing back into GitLab. - -## Limitations - -- Export Issues to CSV is not available at the Group's Issues List. -- Issues are sent as an email attachment, with a 15 MB export limit to ensure - successful delivery across a range of email providers. If you reach the limit, - we suggest narrowing the search before export, perhaps by exporting open and - closed issues separately. -- CSV files are plain text files. This means that the exported CSV file doesn't - contain any issue attachments. +The CSV file has this format: + +- Sort is by title. +- Columns are delimited with commas. +- Fields are quoted with double quotes (`"`) if needed. +- Newline characters separate rows. + +## Columns + +The following columns are included in the CSV file. + +| Column | Description | +|-------------------|-------------| +| Title | Issue `title` | +| Description | Issue `description` | +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| State | `Open` or `Closed` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | +| Assignee Username | Username of the author, with the `@` symbol omitted | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Labels, separated by commas | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| Epic ID | ID of the parent epic | +| Epic Title | Title of the parent epic | + +## Troubleshooting + +When working with exported issues, you might encounter the following issues. + +### Column order + +In GitLab 14.7 and earlier, the first two columns in exported files were `Issue ID` and `URL`, +which caused problems importing data back into GitLab. For more information, see +[issue 34769](https://gitlab.com/gitlab-org/gitlab/-/issues/34769). + +### Size of export + +Issues are sent as an email attachment, with a 15 MB export limit to ensure +successful delivery across a range of email providers. If you reach the limit, +narrow your search before export. For example, consider exporting open and +closed issues separately. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 4068083cd1e..0ea49ff387f 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -6,12 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Design management **(FREE ALL)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. -> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. -> - Design Management section in issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, with a feature flag named `design_management_moved`. In earlier versions, designs were displayed in a separate tab. -> - Design Management section in issues [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. - With Design Management you can upload design assets (including wireframes and mockups) to GitLab issues and keep them stored in a single place. Product designers, product managers, and engineers can collaborate on designs with a single source of truth. @@ -29,7 +23,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. - On self-managed instances, a GitLab administrator must [enable LFS globally](../../../administration/lfs/index.md). - On both GitLab.com and self-managed instances, LFS must be - [enabled for the project itself](../settings/index.md#configure-project-visibility-features-and-permissions). + [enabled for the project itself](../settings/index.md#configure-project-features-and-permissions). If enabled globally, LFS is enabled by default for all projects. If you have disabled it for your project, you must enable it again. @@ -58,7 +52,6 @@ You can upload files of the following types as designs: - JPEG - JPG - PNG -- SVG - TIFF - WEBP @@ -69,7 +62,7 @@ Support for PDF files is tracked in [issue 32811](https://gitlab.com/gitlab-org/ - Design Management data isn't deleted when: - [A project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429). - [An issue is deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427). -- In GitLab 12.7 and later, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) +- Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) and in GitLab 16.1 and later it can be [verified by Geo as well](https://gitlab.com/gitlab-org/gitlab/-/issues/355660). ## View a design @@ -106,9 +99,6 @@ a blue icon (**{file-modified-solid}**) is displayed. ### Zoom in on a design -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. -> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. - You can explore a design in more detail by zooming in and out of the image: - To control the amount of zoom, select plus (`+`) and minus (`-`) @@ -124,7 +114,7 @@ To move around the image while zoomed in, drag the image. Prerequisites: - You must have at least the Developer role for the project. -- In GitLab 13.1 and later, the names of the uploaded files must be no longer than 255 characters. +- The names of the uploaded files must be no longer than 255 characters. To add a design to an issue: @@ -163,6 +153,7 @@ Prerequisites: To do so, [add a design](#add-a-design-to-an-issue) with the same filename. To browse all the design versions, use the dropdown list at the top of the **Designs** section. +It's shown as either **Showing latest version** or **Showing version #N**. ### Skipped designs @@ -172,14 +163,19 @@ When designs are skipped, a warning message is displayed. ## Archive a design -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab 12.4. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/220964) the button from "Delete" to "Archive" in GitLab 13.3. - You can archive individual designs or select a few of them to archive at once. +Archived designs are not permanently lost. +You can browse [previous versions](#add-a-new-version-of-a-design). + +When you archive a design, its URL changes. +If the design isn't available in the latest version, you can link to it only with the version in the +URL. + Prerequisites: - You must have at least the Developer role for the project. +- You can archive only the latest version of a design. To archive a single design: @@ -192,15 +188,10 @@ To archive multiple designs at once: 1. Select the checkboxes on the designs you want to archive. 1. Select **Archive selected**. -NOTE: -Only the latest version of the designs can be archived. -Archived designs are not permanently lost. You can browse -[previous versions](#add-a-new-version-of-a-design). +## Markdown and rich text editors for descriptions <!-- When content_editor_on_issues flag is removed, move version notes - to "Add a design to an issue", update that topic, and delete the one below. --> - -## Markdown and rich text editors for descriptions + to "Add a design to an issue", update that topic, and delete this one. --> > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2. @@ -214,30 +205,28 @@ It's the same editor you use for comments across GitLab. ## Reorder designs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. - You can change the order of designs by dragging them to a new position. ## Add a comment to a design -> Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.8. - You can start [discussions](../../discussions/index.md) on uploaded designs. To do so: -<!-- vale gitlab.SubstitutionWarning = NO --> 1. Go to an issue. 1. Select the design. +<!-- vale gitlab.SubstitutionWarning = NO --> +<!-- Disable Vale so it doesn't catch "click" --> 1. Click or tap the image. A pin is created in that spot, identifying the discussion's location. +<!-- vale gitlab.SubstitutionWarning = YES --> 1. Enter your message. 1. Select **Comment**. -<!-- vale gitlab.SubstitutionWarning = YES --> -You can adjust a pin's position by dragging it around the image. You can use this when your design's -layout has changed, or when you want to move a pin to add a new one in its place. +You can adjust a pin's position by dragging it around the image. +Use this when your design's layout has changed, or to move a pin so you can add a new one in +its place. New discussion threads get different pin numbers, which you can use to refer to them. -In GitLab 12.5 and later, new discussions are output to the issue activity, +New discussions are output to the issue activity, so that everyone involved can participate in the discussion. ## Delete a comment from a design @@ -255,8 +244,6 @@ To delete a comment from a design: ## Resolve a discussion thread on a design -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. - When you're done discussing part of a design, you can resolve the discussion thread. To mark a thread as resolved or unresolved, either: @@ -272,16 +259,10 @@ To revisit a resolved discussion, expand **Resolved Comments** below the visible ## Add a to-do item for a design -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. - To add a [to-do item](../../todos.md) for a design, select **Add a to do** on the design sidebar. ## Refer to a design in Markdown -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in GitLab 13.1. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in GitLab 13.5. - To refer to a design in a [Markdown](../../markdown.md) text box in GitLab, for example, in a comment or description, paste its URL. It's then displayed as a short reference. @@ -297,9 +278,6 @@ It's rendered as: ## Design activity records -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33051) in GitLab 13.1. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/225205) in GitLab 13.2. - User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#access-your-user-profile), [group](../../group/manage.md#view-group-activity), @@ -307,8 +285,6 @@ and [project](../working_with_projects.md#view-project-activity) activity pages. ## GitLab-Figma plugin -> [Introduced](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/issues/2) in GitLab 13.2. - You can use the GitLab-Figma plugin to upload your designs from Figma directly to your issues in GitLab. @@ -316,3 +292,26 @@ To use the plugin in Figma, install it from the [Figma Directory](https://www.fi and connect to GitLab through a personal access token. For more information, see the [plugin documentation](https://gitlab.com/gitlab-org/gitlab-figma-plugin/-/wikis/home). + +## Troubleshooting + +When working with Design Management, you might encounter the following issues. + +### Could not find design + +You might get an error that states `Could not find design`. + +This issue occurs when a design has been [archived](#archive-a-design), +so it's not available in the latest version, and the link you've followed doesn't specify a version. + +When you archive a design, its URL changes. +If the design isn't available in the latest version, it can be linked to only with the version in the URL. + +For example, `https://gitlab.example.com/mygroup/myproject/-/issues/123456/designs/menu.png?version=503554`. +You can no longer access `menu.png` with `https://gitlab.example.com/mygroup/myproject/-/issues/123456/designs/menu.png`. + +The workaround is to select one of the previous versions from the dropdown list at the top of the +**Designs** section. +It's shown as either **Showing latest version** or **Showing version #N**. + +Issue [392540](https://gitlab.com/gitlab-org/gitlab/-/issues/392540) tracks improving this behavior. diff --git a/doc/user/project/issues/img/csv_export_button_v12_9.png b/doc/user/project/issues/img/csv_export_button_v12_9.png Binary files differdeleted file mode 100644 index 702b6439d7c..00000000000 --- a/doc/user/project/issues/img/csv_export_button_v12_9.png +++ /dev/null diff --git a/doc/user/project/issues/img/csv_export_modal.png b/doc/user/project/issues/img/csv_export_modal.png Binary files differdeleted file mode 100644 index f988deec966..00000000000 --- a/doc/user/project/issues/img/csv_export_modal.png +++ /dev/null diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 02cefaa47ef..cb3cbf5fc36 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -18,7 +18,7 @@ Prerequisites: To edit an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select the title of your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the available fields. @@ -54,7 +54,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -88,7 +88,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -117,7 +117,7 @@ Prerequisites: To move an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, select **Move issue**. 1. Search for a project to move the issue to. @@ -138,7 +138,7 @@ Prerequisite: To move multiple issues at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to move. @@ -212,7 +212,7 @@ To close an issue, you can either: - In an [issue board](../issue_board.md), drag an issue card from its list into the **Closed** list. - From any other page in the GitLab UI: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. At the top of the issue, select **Close issue**. @@ -309,7 +309,7 @@ Prerequisites: To disable automatic issue closing: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Branch defaults**. 1. Clear the **Auto-close referenced issues on default branch** checkbox. @@ -357,7 +357,7 @@ Prerequisites: To change issue type: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the issue and select an issue type from the **Issue type** dropdown list: @@ -377,14 +377,14 @@ Prerequisites: To delete an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Delete issue**. Alternatively: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select the title of your issue to view it. 1. Select **Edit title and description** (**{pencil}**). 1. Select **Delete issue**. @@ -399,7 +399,7 @@ You can promote an issue to an [epic](../../group/epics/index.md) in the immedia To promote an issue to an epic: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Promote to epic**. @@ -422,7 +422,7 @@ You can use the `/promote_to_incident` [quick action](../quick_actions.md) to pr To add an issue to an [iteration](../../group/iterations/index.md): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Iteration** section, select **Edit**. 1. From the dropdown list, select the iteration to associate this issue with. @@ -434,7 +434,7 @@ Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#i To view all issues assigned to you: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). +1. On the left sidebar, select **Search or go to**. 1. From the dropdown list, select **Issues assigned to me**. Or: @@ -453,7 +453,7 @@ Or: To filter the list of issues: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. Above the list of issues, select **Search or filter results...**. 1. In the dropdown list that appears, select the attribute you want to filter by. @@ -491,7 +491,7 @@ when you [filter the list of issues](#filter-the-list-of-issues) by: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**. 1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. @@ -504,7 +504,7 @@ To refer to an issue elsewhere in GitLab, you can use its full URL or a short re To copy the issue reference to your clipboard: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**). @@ -528,7 +528,7 @@ For more information about creating comments by sending an email and the necessa To copy the issue's email address: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). @@ -545,7 +545,7 @@ themselves or another project member assigns them. To change the assignee on an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Assignee** section, select **Edit**. 1. From the dropdown list, select the user to add as an assignee. @@ -586,7 +586,7 @@ Prerequisites: To edit health status of an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Health status** section, select **Edit**. 1. From the dropdown list, select the status to add to this issue: diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 4daaaf72683..86d21d07950 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -69,7 +69,7 @@ You can also assign and unassign labels with [quick actions](quick_actions.md): To view the **project's labels**: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. Or: @@ -86,7 +86,7 @@ project or group path where it was created. To view the **group's labels**: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. Or: @@ -108,7 +108,7 @@ Prerequisites: To create a project label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -142,7 +142,7 @@ To do so: To create a group label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -182,7 +182,7 @@ Prerequisites: To edit a **project** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -190,7 +190,7 @@ To edit a **project** label: To edit a **group** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -208,7 +208,7 @@ Prerequisites: To delete a **project** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Either: @@ -221,7 +221,7 @@ To delete a **project** label: To delete a **group** label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Labels**. 1. Either: @@ -251,7 +251,7 @@ Prerequisites: To promote a project label to a group label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. @@ -302,7 +302,7 @@ Prerequisites: To add the default labels to the project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Select **Generate a default set of labels**. @@ -441,7 +441,7 @@ Prerequisites: To prioritize a label: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Labels**. 1. Next to a label you want to prioritize, select the star (**{star-o}**). diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 1e9bd307333..901a8fe9850 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -119,7 +119,7 @@ Prerequisite: To add a user to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Invite members**. 1. If the user: @@ -180,7 +180,7 @@ Prerequisites: To add a group to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Invite a group**. 1. Select a group. @@ -211,7 +211,7 @@ If the importing member's role in the target project is: To import users: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. @@ -236,7 +236,7 @@ Prerequisites: To remove a member from a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Next to the project member you want to remove, select **Remove member**. 1. Optional. On the confirmation dialog, select the @@ -273,7 +273,7 @@ You can filter and sort members in a project. ### Display inherited members -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. @@ -282,7 +282,7 @@ You can filter and sort members in a project. ### Display direct members -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press <kbd>Enter</kbd>. @@ -305,7 +305,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to be a member of. +1. On the left sidebar, select **Search or go to** and find the project you want to be a member of. 1. By the project's name, select **Request Access**.  @@ -329,7 +329,7 @@ Prerequisite: - You must be the project owner. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 3780018bf11..deefe9040fa 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w When you want a group to have access to your project, you can invite [a group](../../group/index.md) to the project. -The group's members get access to the project, which becomes a *shared project*. +The group's direct and inherited members get access to the project, which becomes a *shared project*. ## Example @@ -53,11 +53,12 @@ must be at least as restrictive as that of the project. For example, you can inv > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -You can share a project with a group by inviting that group to the project. +Similar to how you [share a group with another group](../../group/manage.md#share-a-group-with-another-group), +you can share a project with a group by inviting that group to the project. To invite a group to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. Select **Invite a group**. 1. **Select a group** you want to add to the project. @@ -99,7 +100,7 @@ For example, if a group member has the role of Developer, and the group is invit To view the maximum role assigned to a member: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. 1. In the **Max role** column, view the user's maximum assigned role. @@ -109,7 +110,7 @@ In a group, a shared project is a project to which the group members gained acce To view a group's shared projects: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. On the group page, select the **Shared projects** tab. A list of shared projects is displayed. diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md index c1aa729d8c5..304717cf9fc 100644 --- a/doc/user/project/merge_requests/ai_in_merge_requests.md +++ b/doc/user/project/merge_requests/ai_in_merge_requests.md @@ -34,8 +34,7 @@ Provide feedback on this experimental feature in [issue 416537](https://gitlab.c - Title of the merge request - Contents of the description -- Source branch name -- Target branch name +- Diff of changes between the source branch's head and the target branch ## Summarize merge request changes **(ULTIMATE SAAS)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index cbbeac17355..87ff6376ebd 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -89,17 +89,15 @@ To edit a merge request approval rule: ## Add multiple approval rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.10. - In GitLab Premium and Ultimate tiers, you can enforce multiple approval rules on a merge request, and multiple default approval rules for a project. If your tier supports multiple default rules: - When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule - for a project, GitLab displays the **Add approval rule** button even after a rule is defined. + for a project, GitLab displays **Add approval rule**, even after a rule is defined. - When editing or overriding multiple approval rules [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab - displays the **Add approval rule** button even after a rule is defined. + displays **Add approval rule**, even after a rule is defined. When an [eligible approver](#eligible-approvers) approves a merge request, it reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: @@ -111,8 +109,6 @@ For an overview, see [Multiple Approvers](https://www.youtube.com/watch?v=8JQJ58 ## Eligible approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. - To be eligible as an approver for a project, a user must be a member of one or more of these: @@ -140,15 +136,20 @@ users were not explicitly listed in the approval rules. ### Group approvers -You can add a group of users as approvers, but those users count as approvers only if -they have **direct membership** to the group. Inherited members do not count. Group approvers are -restricted to only groups [with share access to the project](../../members/share_project_with_groups.md). +You can add a group of users as approvers. All **direct members** of this group +can approve the rule. **Inherited members** cannot approve the rule. + +Typically the group is a subgroup in your top-level namespace, unless you are +collaborating with an external group. If you are collaborating with another group, +you must [share access to the project](../../members/share_project_with_groups.md) +before assigning the group as a group approver. A user's membership in an approvers group affects their individual ability to approve in these ways: -- A user already part of a group approver who is later added as an individual approver - counts as one approver, and not two. +- Inherited members are not considered approvers. Only direct members can approve merge requests. +- A user from a group approver group who is later _also_ added as an individual approver + counts as one approver, not two. - Merge request authors do not count as eligible approvers on their own merge requests by default. To change this behavior, disable the [**Prevent author approval**](settings.md#prevent-approval-by-author) @@ -157,6 +158,12 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-approvals-by-users-who-add-commits) project setting. +NOTE: +Creating multiple top-level groups to manage groups of users is not necessary, and is +discouraged because GitLab Free [is limited to 5 group members](https://about.gitlab.com/pricing/faq-efficient-free-tier/). +Managing groups of users using subgroups in your top-level namespace enables you +to use a single license. + ### Code owners as eligible approvers > Moved to GitLab Premium in 13.9. @@ -261,12 +268,9 @@ For more information, see [Coverage check approval rule](../../../../ci/testing/ ## Security Approvals **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. +> - Security approvals moved to merge request approvals settings [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. > - Bot comment for approvals [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411656) in GitLab 16.2 [with a flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. Enabled by default. - -FLAG: -On self-managed GitLab, by default the bot comment for approvals is available. To hide the feature, an administrator can [disable the feature flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. -On GitLab.com, the bot comment for approvals is available. +> - Bot comment for approvals [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130827) in GitLab 16.3. Feature flag `security_policy_approval_notification` removed. You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index b520ee41493..ae16eb2a790 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -65,6 +65,7 @@ this setting, unless you configure one of these options: > - Moved to GitLab Premium in 13.9. > - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127744) added in GitLab 16.3 to also include merge commits in this check. +> - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131778) removed in GitLab 16.5. This check now includes merge commits. By default, users who commit to a merge request can still approve it. At both the project level or [instance level](../../../admin_area/merge_requests_approvals.md), diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index ab882af7eda..18f19197f4c 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -158,7 +158,7 @@ rebases and file changes. To add a comment to a merge request file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. Select **Changes**. 1. In the header for the file you want to comment on, select **Comment** (**{comment}**). diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index d9b2ecf0806..ef1554f3b86 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -52,7 +52,7 @@ Commit `G` is added after the cherry-pick. After a merge request is merged, you can cherry-pick all changes introduced by the merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. 1. In the upper-right corner, select **Cherry-pick**: @@ -70,7 +70,7 @@ You can cherry-pick a single commit from multiple locations in your GitLab proje To cherry-pick a commit from the list of all commits for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Commits**. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. @@ -84,7 +84,7 @@ You can cherry-pick commits from any merge request in your project, regardless o whether the merge request is open or closed. To cherry-pick a commit from the list of commits included in a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. @@ -98,7 +98,7 @@ list of commits included in a merge request: You can cherry-pick from the list of previous commits affecting an individual file when you view that file in your project's Git repository: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository** and go to the file changed by the commit. 1. Select **History**, then select the [title](https://git-scm.com/docs/git-commit#_discussion) diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 1fc7188ffea..5ca097da29f 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -8,7 +8,7 @@ type: reference, howto # Commit message templates **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6. +> - Squash commit templates [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6. GitLab uses commit templates to create default messages for specific types of commits. These templates encourage commit messages to follow a particular format, @@ -29,7 +29,7 @@ Prerequisite: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Depending on the type of template you want to create, scroll to either [**Merge commit message template**](#default-template-for-merge-commits) or @@ -66,13 +66,13 @@ GitLab creates a squash commit message with this template: ## Supported variables in commit templates > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) `reviewed_by` variable in GitLab 15.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) `local_reference` variable in GitLab 16.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) `source_project_id` variables in GitLab 16.3. +> - `first_commit` and `first_multiline_commit` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) in GitLab 14.6. +> - `url`, `approved_by`, and `merged_by` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) in GitLab 14.7. +> - `co_authored_by` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) in GitLab 14.7. +> - `all_commits` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) in GitLab 14.9. +> - `reviewed_by` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) in GitLab 15.7. +> - `local_reference` variable [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) in GitLab 16.1. +> - `source_project_id` variables [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128553) in GitLab 16.3. Commit message templates support these variables: diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index ddd2a0ddcb5..502dfd7acab 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -18,7 +18,7 @@ From this tab, you can review commit messages and copy a commit's SHA when you n To see the commits included in a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, then select your merge request. 1. To show a list of the commits in the merge request, newest first, select **Commits** . To read more about the commit, select **Toggle commit description** (**{ellipsis_h}**) @@ -48,7 +48,7 @@ if another merge request: To add previously merged commits to a merge request for more context: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, then select your merge request. 1. Select **Commits**. 1. Scroll to the end of the list of commits, and select **Add previously merged commits**. @@ -63,7 +63,7 @@ force push. To add discussion to a specific commit: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Commits**. 1. Below the commits, in the **Comment** field, enter a comment. 1. Save your comment as either a standalone comment, or a thread: @@ -74,7 +74,7 @@ To add discussion to a specific commit: To view the changes between previously merged commits: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**, then select your merge request. 1. Select **Changes**. 1. By **Compare** (**{file-tree}**), select the commits to compare: diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index fefc6aabddf..e132ddfb729 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,7 +59,7 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. @@ -84,7 +84,7 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index e31460c1997..ec269bec84d 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,7 +19,7 @@ to streamline merge request creation. You can create a merge request from the list of merge requests. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. In the upper-right corner, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. @@ -95,7 +95,7 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Type a branch name and select **New branch**. 1. Above the file list, on the right side, select **Create merge request**. @@ -142,7 +142,7 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select your fork of the repository. 1. On the left sidebar, select **Code > Merge requests**, and select **New merge request**. 1. In the **Source branch** dropdown list box, select the branch in your forked repository as the source branch. @@ -171,7 +171,7 @@ Prerequisites: To create a merge request by sending an email: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. In the upper-right corner, select **Email a new merge request to this project**. An email address is displayed. Copy this address. @@ -216,7 +216,7 @@ scenarios when you create a new merge request: To have merge requests from a fork by default target your own fork (instead of the upstream project), you can change the default. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 15b2e53d7d9..cc7fa050766 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -12,7 +12,7 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index b80698f99c3..e208785fd63 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -57,7 +57,7 @@ information about the dependency: To view dependency information on a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area. Dependent merge requests display information about the total number of dependencies set, such as @@ -105,7 +105,7 @@ Prerequisite: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. In **Merge request dependencies**, paste either the reference or the full URL @@ -120,7 +120,7 @@ Prerequisite: - You must have a role in the project that allows you to edit merge requests. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. Scroll to **Merge request dependencies** and select **Remove** next to the reference diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 3ad07d0377e..ed762979ff1 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -46,7 +46,7 @@ You can view merge requests for your project, group, or yourself. To view all merge requests for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. @@ -55,7 +55,7 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd> To view merge requests for all projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Code > Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -64,7 +64,7 @@ If your group contains subgroups, this view also displays merge requests from th To view all merge requests assigned to you: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). +1. On the left sidebar, select **Search or go to**. 1. From the dropdown list, select **Merge requests assigned to me**. or: @@ -85,16 +85,16 @@ or: To filter the list of merge requests: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Above the list of merge requests, select **Search or filter results...**. 1. From the dropdown list, select the attribute you wish to filter by. Some examples: - [**By environment or deployment date**](#by-environment-or-deployment-date). - **ID**: Enter filter `#30` to return only merge request 30. - User filters: Type (or select from the dropdown list) any of these filters to display a list of users: - - **Approved-By**, for merge requests already approved by a user. **(PREMIUM)**. + - **Approved-By**, for merge requests already approved by a user. **(PREMIUM ALL)**. - **Approver**, for merge requests that this user is eligible to approve. - (For more information, read about [Code owners](../codeowners/index.md)). **(PREMIUM)** + (For more information, read about [Code owners](../codeowners/index.md)). **(PREMIUM ALL)** - **Reviewer**, for merge requests reviewed by this user. 1. Select or type the operator to use for filtering the attribute. The following operators are available: @@ -156,7 +156,7 @@ To assign the merge request to a user, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in a merge request, or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. @@ -176,7 +176,7 @@ accountable for it: To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want @@ -312,7 +312,7 @@ On GitLab.com, this feature is enabled for GitLab team members only. To understand the history of a merge request, filter its activity feed to show you only the items that are relevant to you. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select a merge request. 1. Scroll to **Activity**. @@ -341,22 +341,7 @@ sort order by clicking the sort button on the right. > Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. -In a merge request, you can resolve a thread when you want to finish a conversation. - -Prerequisites: - -- You must have at least the Developer role - or be the author of the change being reviewed. -- Resolvable threads can be added only to merge requests. It doesn't work - for comments in issues, commits, or snippets. - -To resolve a thread: - -1. Go to the thread. -1. Do one of the following: - - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**). - - Below the last reply, in the **Reply** field, select **Resolve thread**. - - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. +In a merge request, you can [resolve a thread](../../discussions/index.md#resolve-a-thread) when you want to finish a conversation. At the top of the page, the number of unresolved threads is updated: @@ -390,7 +375,7 @@ You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, the **Unresolved threads** counter in a merge request is shown in orange when at least one thread remains unresolved. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Merge checks** section, select the **All threads must be resolved** checkbox. 1. Select **Save changes**. @@ -400,7 +385,7 @@ is shown in orange when at least one thread remains unresolved. You can set merge requests to automatically resolve threads when lines are modified with a new push. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Merge options** section, select **Automatically resolve merge request diff threads when they become outdated**. diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 16482d92d7e..77dcb269071 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -39,7 +39,7 @@ To do this when pushing from the command line, use the `merge_request.merge_when To do this from the GitLab user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select the merge request to edit. 1. Scroll to the merge request reports section. @@ -63,7 +63,7 @@ Prerequisites: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select the merge request to edit. 1. Scroll to the merge request reports section. @@ -79,7 +79,7 @@ merge. This configuration works for both: - GitLab CI/CD pipelines. - Pipelines run from an [external CI integration](../integrations/index.md#available-integrations). -As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) +As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md#disable-cicd-in-a-project) does not disable this feature, but you can use pipelines from external CI providers with it. @@ -90,7 +90,7 @@ Prerequisites: To enable this setting: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Scroll to **Merge checks**, and select **Pipelines must succeed**. This setting also prevents merge requests from being merged if there is no pipeline, @@ -111,7 +111,7 @@ Prerequisite: To change this behavior: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Under **Merge checks**: - Select **Pipelines must succeed**. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 7eac0e8839a..959ada4928e 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -26,7 +26,7 @@ gitGraph ## Configure a project's merge method -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Select your desired **Merge method** from these options: - Merge commit diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 14e2ff84eae..7e6bf606f10 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -30,7 +30,7 @@ Prerequisites: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area, and find the report showing when the merge request was merged. @@ -55,7 +55,7 @@ Prerequisites: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. If you know the merge request that contains the commit: 1. Select **Code > Merge requests**, then identify and select your merge request. 1. Select **Commits**, then select the title of the commit you want to revert. This displays the commit in the **Changes** tab of your merge request. diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png Binary files differdeleted file mode 100644 index 70db0d79eaf..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v16_3.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v16_3.png Binary files differnew file mode 100644 index 00000000000..9c3ecebd395 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v16_3.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e4882134654..c09071e856c 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -10,7 +10,7 @@ type: index, reference [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) to propose changes. Your team leaves [comments](../../../discussions/index.md) on -your merge request, and makes [code suggestions](suggestions.md) you can accept +your merge request, and makes [Code Suggestions](suggestions.md) you can accept from the user interface. When your work is reviewed, your team members can choose to accept or reject it. @@ -21,17 +21,24 @@ review merge requests in Visual Studio Code. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Merge request review](https://www.youtube.com/watch?v=2MayfXKpU08&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=183). -## Suggested reviewers **(ULTIMATE SAAS)** +## GitLab Duo Suggested Reviewers **(ULTIMATE SAAS)** > - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/experiment-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6. > - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10. -GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar. +GitLab uses machine learning to suggest reviewers for your merge request. - +To suggest reviewers, GitLab uses: -For more information, see [Data usage in Suggested Reviewers](data_usage.md). +- The changes in the merge request +- The project's contribution graph + +GitLab Duo Suggested Reviewers also integrates with Code Owners, profile status, and merge request rules, helping you make a more informed decision when choosing reviewers that can meet your review criteria. + + + +For more information, see [Data usage in GitLab Duo Suggested Reviewers](data_usage.md). ### Enable suggested reviewers @@ -73,11 +80,40 @@ If you [approve a merge request](../approvals/index.md#approve-a-merge-request) are shown in the reviewer list, a green check mark **{check-circle-filled}** displays next to your name. +### Request a review + +To assign a reviewer to a merge request, in a text area in +the merge request, use the `/assign_reviewer @user` +[quick action](../../quick_actions.md#issues-merge-requests-and-epics). Alternatively: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. On the right sidebar, in the **Reviewers** section, select **Edit**. +1. Search for the user you want to assign, and select the user. + +The merge request is added to the user's review requests. + +#### From multiple users **(PREMIUM ALL)** + +> Moved to GitLab Premium in 13.9. + +To assign multiple reviewers to a merge request, in a text area in +the merge request, use the `/assign_reviewer @user` +[quick action](../../quick_actions.md#issues-merge-requests-and-epics). Alternatively: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. On the right sidebar, in the **Reviewers** section, select **Edit**. +1. From the dropdown list, select all the users you want + to assign to the merge request. + +To remove a reviewer, clear the user from the same dropdown list. + ### Download merge request changes as a diff To download the changes included in a merge request as a diff: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Plain diff**. @@ -100,7 +136,7 @@ curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git a To download the changes included in a merge request as a patch file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Patches**. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 4857d58933a..2b046399c4e 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -14,7 +14,7 @@ merge request, authored by the user who suggested the changes. ## Create suggestions -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. On the secondary menu, select **Changes**. 1. Find the lines of code you want to change. @@ -92,7 +92,7 @@ Prerequisites: To apply suggested changes directly from the merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. Find the comment containing the suggestion you want to apply. - To apply suggestions individually, select **Apply suggestion**. @@ -140,7 +140,7 @@ Merge requests created from forks use the template defined in the target project To meet your project's needs, you can customize these messages and include other placeholder variables: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Scroll to **Merge suggestions**, and alter the text to meet your needs. See [Supported variables](#supported-variables) for a list of placeholders @@ -172,7 +172,7 @@ For example, to customize the commit message to output To reduce the number of commits added to your branch, you can apply multiple suggestions in a single commit. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. For each suggestion you want to apply, and select **Add suggestion to batch**. 1. Optional. To remove a suggestion, select **Remove from batch**. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index ea999fe039a..a6d55ee44e2 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -71,7 +71,7 @@ Prerequisites: To configure the default squashing behavior for all merge requests in your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. In the **Squash commits when merging** section, select your desired behavior: - **Do not allow**: Squashing is never performed, and the option is not displayed. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index e0e65c99433..f87d379b974 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -36,7 +36,7 @@ see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869). By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Select the **Status checks must succeed** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 7c9a5a37292..65cc9477c49 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -13,7 +13,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Burndown charts -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. > - Moved to GitLab Premium in 13.9. @@ -32,13 +31,13 @@ For an overview, check the video demonstration on [Mapping work versus time with To view a project's burndown chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. To view a group's burndown chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. @@ -112,13 +111,13 @@ Burnup charts show the assigned and completed work for a milestone. To view a project's burnup chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. To view a group's burnup chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Plan > Milestones**. 1. Select a milestone from the list. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 4bb751aedc5..328e56e2bd8 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -37,7 +37,7 @@ For information about project and group milestones API, see: To view the milestone list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. In a project, GitLab displays milestones that belong to the project. @@ -46,7 +46,7 @@ In a group, GitLab displays milestones that belong to the group and all projects ### View milestones in a project with issues turned off If a project has issue tracking -[turned off](../settings/index.md#configure-project-visibility-features-and-permissions), +[turned off](../settings/index.md#configure-project-features-and-permissions), to get to the milestones page, enter its URL. To do so: @@ -66,7 +66,7 @@ You might not see some milestones because they're in projects or groups you're n To do so: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. On the left sidebar, select **Milestones**. @@ -121,7 +121,7 @@ Prerequisites: To create a milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. 1. Select **New milestone**. 1. Enter the title. @@ -140,7 +140,7 @@ Prerequisites: To edit a milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. 1. Select a milestone's title. 1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. @@ -157,7 +157,7 @@ Prerequisites: To edit a milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Milestones**. 1. Select a milestone's title. 1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. @@ -183,7 +183,7 @@ Prerequisites: To promote a project milestone: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Milestones**. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index d4516746afc..0aad9a69743 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -70,7 +70,7 @@ on how to use GitLab as a backend for the MLflow Client. To list the current active experiments, either go to `https/-/ml/experiments` or: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Model experiments**. 1. To display all candidates that have been logged, along with their metrics, parameters, and metadata, select an experiment. 1. To display details for a candidate, select **Details**. diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md index 3e78cc5b7f2..9cedb5780ed 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -24,7 +24,7 @@ Prerequisites: - A [personal](../../../../user/profile/personal_access_tokens.md), [project](../../../../user/project/settings/project_access_tokens.md), or [group](../../../../user/group/settings/group_access_tokens.md) access token with at least the Developer role and the `api` permission. - The project ID. To find the project ID: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. To use MLflow client compatibility from a local environment: @@ -83,6 +83,7 @@ tested. More information can be found in the [MLflow Documentation](https://www. | `set_experiment` | Yes | 15.11 | | | `get_run` | Yes | 15.11 | | | `start_run` | Yes | 15.11 | (16.3) If a name is not provided, the candidate receives a random nickname. | +| `search_runs` | Yes | 15.11 | (16.4) `experiment_ids` supports only a single experiment ID with order by column or metric. | | `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty. Does not support directories. | | `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty. Does not support directories. | | `log_batch` | Yes | 15.11 | | diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 8bf4875ba1e..d8e4fce41ef 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -43,7 +43,7 @@ this document for an [overview on DNS records](dns_concepts.md). To add your custom domain to GitLab Pages: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. @@ -113,7 +113,7 @@ Subdomains (`subdomain.example.com`) require: Whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), -without any `/project-name`. +without any path.  @@ -154,7 +154,7 @@ If you're using Cloudflare, check After you have added all the DNS records: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). @@ -246,7 +246,7 @@ meet these requirements. - To add the certificate at the time you add a new domain: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. @@ -255,7 +255,7 @@ meet these requirements. - To add the certificate to a domain previously added: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). @@ -283,7 +283,7 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Select the **Force HTTPS (requires valid certificates)** checkbox. 1. Select **Save changes**. @@ -303,7 +303,7 @@ You can edit a custom domain to: To edit a custom domain: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. @@ -313,7 +313,7 @@ After a custom domain is deleted, the domain is no longer verified in GitLab and To delete and remove a custom domain: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 1. When prompted, select **Remove domain**. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 5c1fc41d947..3d9fe4b04e9 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,7 +42,7 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. Turn on the **Automatic certificate management using Let's Encrypt** toggle. @@ -69,7 +69,7 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). @@ -84,7 +84,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index f8ee3f10d1e..90fc1a72eb3 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,7 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the **Add** (**{plus}**) dropdown list, select **New file**. 1. From the **Select a template type** dropdown list, select `.gitlab-ci.yml`. 1. From the **Apply a template** dropdown list, in the **Pages** section, select the name of your SSG. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index ab3c12427b3..8fa927bd61c 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -33,7 +33,7 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. A **Get Started with Pages** form appears. If this form is not available, diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index e44a7bf347f..ec511ee0a5f 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -25,13 +25,13 @@ For GitLab self-managed instances, replace `example.io` with your instance's Pages domain. For GitLab.com, Pages domains are `*.gitlab.io`. -| Type of GitLab Pages | The name of the project created in GitLab | Website URL | +| Type of GitLab Pages | Example path of a project in GitLab | Website URL | | -------------------- | ------------ | ----------- | -| User pages | `username.example.io` | `http(s)://username.example.io` | -| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` | -| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` | -| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| -| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| +| User pages | `username/username.example.io` | `http(s)://username.example.io` | +| Group pages | `acmecorp/acmecorp.example.io` | `http(s)://acmecorp.example.io` | +| Project pages owned by a user | `username/my-website` | `http(s)://username.example.io/my-website` | +| Project pages owned by a group | `acmecorp/webshop` | `http(s)://acmecorp.example.io/webshop`| +| Project pages owned by a subgroup | `acmecorp/documentation/product-manual` | `http(s)://acmecorp.example.io/documentation/product-manual`| WARNING: There are some known [limitations](introduction.md#subdomains-of-subdomains) @@ -72,7 +72,7 @@ To understand Pages domains clearly, read the examples below. **General example:** - On GitLab.com, a project site is always available under - `https://namespace.gitlab.io/project-name` + `https://namespace.gitlab.io/project-slug` - On GitLab.com, a user or group website is available under `https://namespace.gitlab.io/` - On your GitLab instance, replace `gitlab.io` above with your @@ -86,7 +86,7 @@ The `baseurl` option might be named differently in some static site generators. Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, -whenever you publish a project website (`namespace.gitlab.io/project-name`), +whenever you publish a project website (for example, `namespace.gitlab.io/project-slug`), you must look for this configuration (base URL) on your static site generator's documentation and set it up to reflect this pattern. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 4585ee2cecd..664c80e0351 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -47,9 +47,9 @@ depending on your static generator configuration. If the case of `404.html`, there are different scenarios. For example: -- If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/existing_file`, GitLab Pages tries to serve first - `/projectname/404.html`, and then `/404.html`. +- If you use project Pages (served under `/project-slug/`) and try to access + `/project-slug/non/existing_file`, GitLab Pages tries to serve first + `/project-slug/404.html`, and then `/404.html`. - If you use user or group Pages (served under `/`) and try to access `/non/existing_file` GitLab Pages tries to serve `/404.html`. - If you use a custom domain and try to access `/non/existing_file`, GitLab @@ -64,7 +64,7 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Select **Remove pages**. @@ -87,7 +87,7 @@ For [group websites](../../project/pages/getting_started_part_one.md#user-and-gr the group must be at the top level and not a subgroup. For [project websites](../../project/pages/getting_started_part_one.md#project-website-examples), -you can create your project first and access it under `http(s)://namespace.example.io/projectname`. +you can create your project first and access it under `http(s)://namespace.example.io/project-path`. ## Enable unique domains @@ -99,7 +99,7 @@ By default, every project in a group shares the same domain, for example, `group To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Pages**. 1. Select the **Use unique domain** checkbox. 1. Select **Save changes**. @@ -308,7 +308,7 @@ For a list of known issues, see the GitLab [public issue tracker](https://gitlab This problem most likely results from a missing `index.html` file in the public directory. If after deploying a Pages site a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name -such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`. +such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-slug/test.html`. The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/jobs/job_artifacts.md#download-job-artifacts) from the latest pipeline. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 5f1f5bc59ae..ff1f138e5b7 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -47,14 +47,14 @@ To create redirects, create a configuration file named `_redirects` in the configured at the instance level. Only the first matching rules within the configured maximum are processed. The default file size limit is 64 KB, and the default maximum number of rules is 1,000. - If your GitLab Pages site uses the default domain name (such as - `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: + `namespace.gitlab.io/project-slug`) you must prefix every rule with the path: ```plaintext - /projectname/wardrobe.html /projectname/narnia.html 302 + /project-slug/wardrobe.html /project-slug/narnia.html 302 ``` - If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), - no project name prefix is needed. For example, if your custom domain is `example.com`, + no project path prefix is needed. For example, if your custom domain is `example.com`, your `_redirects` file would look like: ```plaintext @@ -69,7 +69,7 @@ the file instead of your redirect. For example, if the files `hello.html` and is ignored because `hello.html` exists: ```plaintext -/projectname/hello.html /projectname/world.html 302 +/project-slug/hello.html /project-slug/world.html 302 ``` GitLab does not support Netlify @@ -210,8 +210,7 @@ would **not** match a request URL like `/old/file`: ## Debug redirect rules If a redirect isn't working as expected, or you want to check your redirect syntax, visit -`https://[namespace.gitlab.io]/projectname/_redirects`, replacing `[namespace.gitlab.io]` with -your domain name. The `_redirects` file isn't served directly, but your browser +`[your pages url]/_redirects`. The `_redirects` file isn't served directly, but your browser displays a numbered list of your redirect rules, and whether the rule is valid or invalid: ```plaintext diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 505f1a530cd..fac07a1313a 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -95,7 +95,7 @@ Prerequisites: To protect a branch: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -133,7 +133,7 @@ Prerequisite: To protect a branch for all the projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -157,7 +157,7 @@ Prerequisite: To protect multiple branches at the same time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -193,7 +193,7 @@ from the command line or from a Git client application. To create a new branch through the user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Select **New branch**. 1. Fill in the branch name and select an existing branch, tag, or commit to @@ -205,7 +205,7 @@ To create a new branch through the user interface: You can force everyone to submit a merge request, rather than allowing them to check in directly to a protected branch: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -218,7 +218,7 @@ check in directly to a protected branch: You can allow everyone with write access to push to the protected branch. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -247,7 +247,7 @@ Prerequisites: To allow a deploy key to push to a protected branch: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -267,7 +267,7 @@ protected branches. To protect a new branch and enable force push: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -280,7 +280,7 @@ To protect a new branch and enable force push: To enable force pushes on branches that are already protected: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -322,7 +322,7 @@ the applicable rules have **Required approval from code owners** enabled. To protect a new branch and enable Code Owner's approval: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -333,7 +333,7 @@ To protect a new branch and enable Code Owner's approval: To enable Code Owner's approval on branches that are already protected: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. Select **Add protected branch**. @@ -366,7 +366,7 @@ for details about the pipelines security model. Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the branch name and select **Yes, delete protected branch**. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 8686d02271c..b312acd49f4 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -31,7 +31,7 @@ Prerequisites: - You must have at least the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected tags**. 1. Select **Add new**. @@ -77,7 +77,9 @@ all matching tags: A tag and a branch with identical names can contain different commits. If your tags and branches use the same names, users running `git checkout` commands might check out the _tag_ `qa` when they instead meant to check out -the _branch_ `qa`. +the _branch_ `qa`. As an added security measure, avoid creating tags with the +same name as branches. Confusing the two could lead to potential +security or operational issues. To prevent this problem: @@ -111,7 +113,7 @@ Prerequisites: To allow a deploy key to create a protected tag: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Protected tags**. 1. From the **Tag** dropdown list, select the tag you want to protect. @@ -129,7 +131,7 @@ Prerequisite: To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Tags**. 1. Next to the tag you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index d0a938e054d..e8451e3049d 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -6,119 +6,97 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Push options **(FREE ALL)** -GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) -to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. +When you push changes to a branch, you can use client-side +[Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt). +In Git 2.10 and later, use Git push options to: -Currently, there are push options available for: +- [Skip CI jobs](#push-options-for-gitlab-cicd) +- [Push to merge requests](#push-options-for-merge-requests) -- [Skipping CI jobs](#push-options-for-gitlab-cicd) -- [Merge requests](#push-options-for-merge-requests) - -NOTE: -Git push options are only available with Git 2.10 or newer. - -For Git versions 2.10 to 2.17 use `--push-option`: +In Git 2.18 and later, you can use either the long format (`--push-option`) or the shorter `-o`: ```shell -git push --push-option=<push_option> +git push -o <push_option> ``` -For version 2.18 and later, you can use the above format, or the shorter `-o`: +In Git 2.10 to 2.17, you must use the long format: ```shell -git push -o <push_option> +git push --push-option=<push_option> ``` +For server-side controls and enforcement of best practices, see +[push rules](repository/push_rules.md) and [server hooks](../../administration/server_hooks.md). + ## Push options for GitLab CI/CD You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. -| Push option | Description | Introduced in version | -| ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | -| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI integrations, such as Jenkins. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | -| `integrations.skip_ci` | Skip push events for CI integrations, such as Atlassian Bamboo, Buildkite, Drone, Jenkins, and JetBrains TeamCity. | [16.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123837) | +| Push option | Description | Example | +|--------------------------------|-------------|---------| +| `ci.skip` | Do not create a CI/CD pipeline for the latest push. Skips only branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI/CD integrations, such as Jenkins. | `git push -o ci.skip` | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to the CI/CD pipeline, if one is created due to the push. Passes variables only to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | `git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600"` | +| `integrations.skip_ci` | Skip push events for CI/CD integrations, such as Atlassian Bamboo, Buildkite, Drone, Jenkins, and JetBrains TeamCity. Introduced in [GitLab 16.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123837). | `git push -o integrations.skip_ci` | -An example of using `ci.skip`: - -```shell -git push -o ci.skip -``` - -An example of passing some CI/CD variables for a pipeline: - -```shell -git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600" -``` +## Push options for merge requests -An example of using `integrations.skip_ci`: +Git push options can perform actions for merge requests while pushing changes: -```shell -git push -o integrations.skip_ci -``` +| Push option | Description | +|----------------------------------------------|-------------| +| `merge_request.create` | Create a new merge request for the pushed branch. | +| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch`. | +| `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | +| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | +| `merge_request.title="<title>"` | Set the title of the merge request. For example: `git push -o merge_request.title="The title I want"`. | +| `merge_request.description="<description>"` | Set the description of the merge request. For example: `git push -o merge_request.description="The description I want"`. | +| `merge_request.draft` | Mark the merge request as a draft. For example: `git push -o merge_request.draft`. Introduced in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/296673). | +| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. For example: `git push -o merge_request.milestone="3.0"`. Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960). | +| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | +| `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | +| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. Support for usernames added in [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276). | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. Support for usernames added in [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276). | -## Push options for merge requests +## Formats for push options -You can use Git push options to perform certain actions for merge requests at the same -time as pushing changes: - -| Push option | Description | Introduced in version | -| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------- | -| `merge_request.create` | Create a new merge request for the pushed branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch` | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.title="<title>"` | Set the title of the merge request. For example: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.description="<description>"` | Set the description of the merge request. For example: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.draft` | Mark the merge request as a draft. For example: `git push -o merge_request.draft`. | [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/296673) | -| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. For example: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | -| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | - -If you use a push option that requires text with spaces in it, you need to enclose it -in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: +If your push option requires text containing spaces, enclose the text in +double quotes (`"`). You can omit the quotes if there are no spaces. Some examples: ```shell git push -o merge_request.label="Label with spaces" git push -o merge_request.label=Label-with-no-spaces ``` -You can combine push options to accomplish multiple tasks at once, by using -multiple `-o` (or `--push-option`) flags. For example, if you want to create a new -merge request, and target a branch named `my-target-branch`: +To combine push options to accomplish multiple tasks at once, use +multiple `-o` (or `--push-option`) flags. This command creates a +new merge request, targets a branch (`my-target-branch`), and sets auto-merge: ```shell -git push -o merge_request.create -o merge_request.target=my-target-branch +git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds ``` -Additionally if you want the merge request to merge as soon as the pipeline succeeds you can do: +## Create Git aliases for common commands -```shell -git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds -``` +Adding push options to Git commands can create very long commands. If +you use the same push options frequently, create Git aliases for them. +Git aliases are command-line shortcuts for longer Git commands. -## Useful Git aliases +To create and use a Git alias for the +[merge when pipeline succeeds Git push option](#push-options-for-merge-requests): -As shown above, Git push options can cause Git commands to grow very long. If -you use the same push options frequently, it's useful to create -[Git aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). Git aliases -are command line shortcuts for Git which can significantly simplify the use of -long Git commands. +1. In your terminal window, run this command: -### Merge when pipeline succeeds alias + ```shell + git config --global alias.mwps "push -o merge_request.create -o merge_request.target=main -o merge_request.merge_when_pipeline_succeeds" + ``` -To set up a Git alias for the -[merge when pipeline succeeds Git push option](#push-options-for-merge-requests): +1. To use the alias to push a local branch that targets the default branch (`main`) + and auto-merges, run this command: -```shell -git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" -``` + ```shell + git mwps origin <local-branch-name> + ``` -Then to quickly push a local branch that targets the default branch and merges when the -pipeline succeeds: +## Related topics -```shell -git mwps origin <local-branch-name> -``` +- [Git aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases) in the Git documentation diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index aee052631fc..097c726d163 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -146,10 +146,13 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do |:--------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| | `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign one or more users. | | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Assign yourself. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412275) in GitLab 16.5 | | `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | +| `/checkin_reminder` | **{dotted-circle}** No| **{check-circle}** Yes | **{dotted-circle}** No | Set checkin reminder cadence. Options are `weekly`, `twice-monthly`, `monthly`, `never`. This action is behind a feature flag. | | `/clear_health_status` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | | `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | | `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/confidential` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark work item as confidential. [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412276) in GitLab 16.4. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/health_status <value>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, or `at_risk`. | @@ -160,6 +163,7 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Remove due date. | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. | @@ -168,6 +172,7 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | Remove all assignees. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | | `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe to notifications. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420796) in GitLab 16.4 | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 8e65514cd1d..17ea0e3f694 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -74,7 +74,7 @@ Prerequisites: To create a release in the Releases page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release @@ -215,7 +215,7 @@ To delete a release, use either the In the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Deploy > Releases**. 1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). @@ -287,22 +287,40 @@ are defined as [crontab](https://crontab.guru/) entries. If the job that's executing is in a freeze period, GitLab CI/CD creates an environment variable named `$CI_DEPLOY_FREEZE`. -To prevent the deployment job from executing, create a `rules` entry in your -`.gitlab-ci.yml`, for example: +To prevent the deployment job from executing in multiple projects in a group, +define the `.freezedeployment` job in a file shared across the group. +Use the [`includes`](../../../ci/yaml/includes.md) keyword to incorporate the +template in your project's `.gitlab-ci.yml` file: ```yaml -deploy_to_production: +.freezedeployment: stage: deploy - script: deploy_to_prod.sh + before_script: + - '[[ ! -z "$CI_DEPLOY_FREEZE" ]] && echo "INFRASTRUCTURE OUTAGE WINDOW" && exit 1; ' rules: - - if: $CI_DEPLOY_FREEZE == null + - if: '$CI_DEPLOY_FREEZE' + when: manual + allow_failure: true + - when: on_success +``` + +To prevent the deployment job from executing, use the [`extends`](../../../ci/yaml/index.md#extends) keyword in the `deploy_to_production` job of your `.gitlab-ci.yml` file to inherit the configuration from the `.freezedeployment` template job: + +```yaml +deploy_to_production: + extends: .freezedeployment + script: deploy_to_prod.sh environment: production ``` +This configuration blocks deployment jobs conditionally and maintains pipeline continuity. When a freeze period is defined, the job fails and the pipeline can proceed without deployment. Manual deployment is possible after the freeze period. + +This approach offers deployment control during critical maintenance, and ensures the uninterrupted flow of the CI/CD pipeline. + To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Select **Expand** to see the deploy freeze table. @@ -342,7 +360,7 @@ Releases can be made accessible to non-project members while keeping repository- projects that use releases as a way to give access to new versions of software but do not want the source code to be public. -To make releases available publicly, set the following [project settings](../settings/index.md#project-feature-settings): +To make releases available publicly, set the following [project settings](../settings/index.md#configure-project-features-and-permissions): - Repository is enabled and set to **Only Project Members** - Releases is enabled and set to **Everyone With Access** diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index e1de9cbdc1c..9daa6705ad8 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Release CLI tool -The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli) tool +The [GitLab Release CLI (`release-cli`)](https://gitlab.com/gitlab-org/release-cli) is a command-line tool for managing releases from the command line or from a CI/CD pipeline. You can use the release CLI to create, update, modify, and delete releases. diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index ec3d63462f3..6bbc0b8123a 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -4,7 +4,7 @@ group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Connect a remote machine to the Web IDE (Beta) **(FREE ALL)** +# Tutorial: Connect a remote machine to the Web IDE **(FREE ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 16110af984a..8ca505be500 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -4,7 +4,7 @@ group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Remote development (Beta) **(FREE ALL)** +# Remote development **(FREE ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/371084) in GitLab 15.7. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index e123debb724..fdc822ca49f 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -42,7 +42,7 @@ Prerequisites: To update the default branch for an individual [project](../../index.md): -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Branch defaults**. For **Default branch**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close @@ -68,7 +68,7 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. @@ -85,7 +85,7 @@ overrides it. Users with the Owner role of groups and subgroups can configure the default branch name for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. @@ -128,7 +128,7 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. @@ -146,7 +146,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand the **Default branch** section. @@ -167,7 +167,7 @@ can be overridden on a per-group basis by the group's owner. In [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index f7445ffe950..f33d443cd7f 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -11,7 +11,7 @@ Branches are versions of a project's working tree. When you create a new cannot be deleted) for your repository. Default branch settings can be configured at the project, subgroup, group, or instance level. -As your project grows, your team [creates](../web_editor.md#create-a-branch) more +As your project grows, your team creates more branches, preferably by following [branch naming patterns](#prefix-branch-names-with-issue-numbers). Each branch represents a set of changes, which allows development work to be done in parallel. Development work in one branch does not affect another branch. @@ -27,9 +27,13 @@ Branches are the foundation of development in a project: ## Create branch +Prerequisites: + +- You must have at least the Developer role for the project. + To create a new branch from the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. On the top right, select **New branch**. 1. Enter a **Branch name**. @@ -44,15 +48,15 @@ you can add one. Prerequisites: -- You must have at least the Developer role in the project. -- Unless you have the Maintainer or Owner roles, the +- You must have at least the Developer role for the project. +- If you don't have the Maintainer or Owner role, the [default branch protection](../../../group/manage.md#change-the-default-branch-protection-of-a-group) must be set to `Partially protected` or `Not protected` for you to push a commit to the default branch. To add a [default branch](default.md) to an empty project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Scroll to **The repository for this project is empty** and select the type of file you want to add. 1. In the Web IDE, make any desired changes to this file, then select **Create commit**. @@ -64,7 +68,7 @@ GitLab creates a default branch and adds your file to it. Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Developer role for the project. When viewing an issue, you can create an associated branch directly from that page. Branches created this way use the @@ -73,11 +77,11 @@ including variables. Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Developer role for the project. To create a branch from an issue: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues** and find your issue. 1. Below the issue description, find the **Create merge request** dropdown list, and select **{chevron-down}** to display the dropdown list. @@ -89,7 +93,7 @@ To create a branch from an issue: ## Manage and protect branches -GitLab provides you multiple methods to protect individual branches. These methods +GitLab provides multiple methods to protect individual branches. These methods ensure your branches receive oversight and quality checks from their creation to their deletion: - The [default branch](default.md) in your project receives extra protection. @@ -104,19 +108,19 @@ ensure your branches receive oversight and quality checks from their creation to You can manage your branches: - With the GitLab user interface. -- With the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- With Git on the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). - With the [Branches API](../../../../api/branches.md). ### View all branches To view and manage your branches in the GitLab user interface: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. On this page, you can: -- See all branches, active branches, or stale branches. +- See all branches, or filter to see only active or stale branches. - Create new branches. - [Compare branches](#compare-branches). - Delete merged branches. @@ -145,19 +149,19 @@ and their protection methods: Prerequisites: -- You must have at least the Maintainer role in the project. +- You must have at least the Maintainer role for the project. To view the **Branch rules overview** list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. -1. Expand **Branch Rules** to view all branches with protections. +1. Expand **Branch rules** to view all branches with protections. - To add protections to a new branch: 1. Select **Add branch rule**. 1. Select **Create protected branch**. - To view more information about protections on an existing branch: 1. Identify the branch you want more information about. - 1. Select **Details** to see information about its: + 1. Select **View details** to see information about its: - [Branch protections](../../protected_branches.md). - [Approval rules](../../merge_requests/approvals/rules.md). - [Status checks](../../merge_requests/status_checks.md). @@ -173,12 +177,17 @@ GitLab enforces these additional rules on all branches: - No spaces are allowed in branch names. - Branch names with 40 hexadecimal characters are prohibited, because they are similar to Git commit hashes. -Common software packages, like Docker, may enforce +Common software packages, like Docker, can enforce [additional branch naming restrictions](../../../../administration/packages/container_registry.md#docker-connection-error). -For best compatibility with other software packages, use only numbers, hyphens (`-`), -underscores (`_`), and lower-case letters from the ASCII standard table. You -can use forward slashes (`/`) and emoji in branch names, but compatibility with other +For the best compatibility with other software packages, use only: + +- Numbers +- Hyphens (`-`) +- Underscores (`_`) +- Lowercase letters from the ASCII standard table + +You can use forward slashes (`/`) and emoji in branch names, but compatibility with other software packages cannot be guaranteed. Branch names with specific formatting offer extra benefits: @@ -200,7 +209,7 @@ Prerequisites: To change the default pattern for branches created from issues: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Branch defaults**. 1. Scroll to **Branch name template** and enter a value. The field supports these variables: @@ -210,8 +219,13 @@ To change the default pattern for branches created from issues: ### Prefix branch names with issue numbers -To streamline the creation of merge requests, start your branch name with an -issue number. GitLab uses the issue number to import data into the merge request: +To streamline the creation of merge requests, start your Git branch name with the +issue number, followed by a hyphen. +For example, to link a branch to issue `#123`, start the branch name with `123-`. + +The issue and the branch must be in the same project. + +GitLab uses the issue number to import data into the merge request: - The issue is marked as related to the merge request. The issue and merge request display links to each other. @@ -224,21 +238,9 @@ issue number. GitLab uses the issue number to import data into the merge request ## Compare branches -> - Repository filter search box [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. -> - Revision swapping [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. - -The default compare mode uses the `git diff from...to` method, instead of the -`git diff from to` method, to compare branches. The `git diff from...to` method -provides a more human-readable diff, because it does not include unrelated changes -made to the target branch after the source branch was created. - -NOTE: -The `git diff from...to` method shows all changes from a cherry-picked commit as -new changes. It uses the merge base, not the actual commit content, to compare branches. - To compare branches in a repository: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Compare revisions**. 1. Select the **Source** branch to search for your desired branch. Exact matches are shown first. You can refine your search with operators: @@ -247,8 +249,23 @@ To compare branches in a repository: - `*` matches using a wildcard: `branch*cache*` matches `fix/branch-search-cache-expiration`. - You can combine operators: `^chore/*migration$` matches `chore/user-data-migration`. 1. Select the **Target** repository and branch. Exact matches are shown first. -1. Select **Compare** to show the list of commits, and changed files. To reverse - the **Source** and **Target**, select **Swap revisions**. +1. Below **Show changes**, select the method to compare branches: + <!-- vale gitlab.SubstitutionWarning = NO --> + <!-- Disable Vale so it doesn't flag "since" --> + - **Only incoming changes from source** (default) shows differences from the source branch since + the latest common commit on both branches. + It doesn't include unrelated changes made to the target branch after the source branch was created. + This method uses the `git diff <from>...<to>` + [Git command](https://git-scm.com/docs/git-diff#Documentation/git-diff.txt-emgitdiffemltoptionsgtltcommitgtltcommitgt--ltpathgt82308203-1). + To compare branches, this method uses the merge base instead of the actual commit, so + changes from cherry-picked commits are shown as new changes. + - **Include changes to target since source was created** shows all the differences between the two + branches. + This method uses the `git diff <from> <to>` + [Git command](https://git-scm.com/docs/git-diff#Documentation/git-diff.txt-emgitdiffemltoptionsgt--merge-baseltcommitgtltcommitgt--ltpathgt82308203). + <!-- vale gitlab.SubstitutionWarning = YES --> +1. Select **Compare** to show the list of commits, and changed files. +1. Optional. To reverse the **Source** and **Target**, select **Swap revisions** (**{substitute}**). ## Delete merged branches @@ -259,15 +276,15 @@ Merged branches can be deleted in bulk if they meet all of these criteria: Prerequisites: -- You must have at least the Developer role in the project. +- You must have at least the Developer role for the project. To do this: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. On the upper right corner of the page, select **More** **{ellipsis_v}**. 1. Select **Delete merged branches**. -1. In the modal window, enter the word `delete` to confirm, then select **Delete merged branches**. +1. In the dialog, enter the word `delete` to confirm, then select **Delete merged branches**. ## Related topics @@ -323,7 +340,7 @@ Error: Could not set the default branch. Do you have a branch named 'HEAD' in yo To fix this problem: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Branches**. 1. Search for a branch named `HEAD`. 1. Make sure the branch has no uncommitted changes. diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md deleted file mode 100644 index 6f18aabaa46..00000000000 --- a/doc/user/project/repository/code_suggestions.md +++ /dev/null @@ -1,375 +0,0 @@ ---- -stage: AI-powered -group: AI Model Validation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference ---- - -# Code Suggestions (Beta) **(FREE ALL)** - -> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](../../../policy/experiment-beta-support.md#beta) for early access Ultimate customers on GitLab.com. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](../../../policy/experiment-beta-support.md#beta). -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1. -> - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta) on self-managed GitLab. -> - Code suggestions in the GitLab WebIDE enabled for all GitLab-hosted customers. -> - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. - -WARNING: -This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). -Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your [feedback](#feedback). - -Write code more efficiently by using generative AI to suggest code while you're developing. - -Code Suggestions are available: - -- To users of GitLab SaaS (by default) and self-managed GitLab Enterprise Edition (when requested). Code Suggestions are not available for GitLab Community Edition. -- In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. -- In the GitLab WebIDE. - -<div class="video-fallback"> - <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">View an end-to-end demo of Code Suggestions in VS Code</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> -</figure> - -Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). -Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). - -## Supported languages - -The best results from Code Suggestions are expected [for languages the Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_coding_languages) directly support: - -- C++ -- C# -- Go -- Google SQL -- Java -- JavaScript -- Kotlin -- PHP -- Python -- Ruby -- Rust -- Scala -- Swift -- TypeScript - -### Supported code infrastructure interfaces - -Code Suggestions includes [Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) support for the following infrastructure as code interfaces: - -- Google Cloud CLI -- Kubernetes Resource Model (KRM) -- Terraform - -Suggestion quality for other languages and using natural language code comments to request completions may not yet result in high-quality suggestions. - -### Supported languages in IDEs - -Editor support for languages is documented in the following table. - -| Language | VS Code | JetBrains IDEs | Visual Studio | Neovim | -|---------------------------------|--------------------------------------------------------------|------------------------------|---------------|--------| -| C++ | ✓ | | ✓ | | -| C# | ✓ | ✓ | ✓ | | -| Go | ✓ | ✓ (IDEA Ultimate / GoLand) | | | -| Google SQL | | | | | -| Java | ✓ | ✓ | | | -| JavaScript | ✓ | ✓ | | | -| Kotlin | ✓ | ✓ | | | -| PHP | ✓ | ✓ (IDEA Ultimate) | | | -| Python | ✓ | ✓ | | ✓ | -| Ruby | ✓ | ✓ (IDEA Ultimate / RubyMine) | | ✓ | -| Rust | ✓ | ✓ | | | -| Scala | ✓ | ✓ | | | -| Swift | ✓ | ✓ | | | -| TypeScript | ✓ | ✓ | | | -| Google Cloud CLI | | | | | -| Kubernetes Resource Model (KRM) | | | | | -| Terraform | ✓ (Requires 3rd party extension providing Terraform support) | | | | - -## Supported editor extensions - -Code Suggestions supports a variety of popular editors including: - -- VS Code, using [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). -- [GitLab WebIDE (VS Code in the Cloud)](../../project/web_ide/index.md), with no additional configuration. -- Microsoft Visual Studio, using the [Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). -- JetBrains IDEs, using the [GitLab plugin](https://plugins.jetbrains.com/plugin/22325-gitlab). -- Neovim, using the [`gitlab.vim` plugin](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim). - -A [GitLab Language Server for Code Suggestions](https://gitlab.com/gitlab-org/editor-extensions/gitlab-language-server-for-code-suggestions) -is also in process. -This improvement should result in: - -- Faster iteration and standardization of the IDE extensions. -- The ability to use Code Suggestions even when an official editor extension isn't available. - -## Enable Code Suggestions on GitLab SaaS **(FREE SAAS)** - -Code Suggestions can be enabled [for all members of a group](../../group/manage.md#enable-code-suggestions). - -Each individual user must also choose to enable Code Suggestions. - -### Enable Code Suggestions for an individual user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta). - -Each user can enable Code Suggestions for themselves: - -1. On the left sidebar, select your avatar. -1. Select **Preferences**. -1. In the **Code Suggestions** section, select the **Enable Code Suggestions** checkbox. -1. Select **Save changes**. - -If Code Suggestions is enabled for the group, the group setting overrides the user setting. - -NOTE: -This setting controls Code Suggestions for all IDEs. Support for [more granular control per IDE](https://gitlab.com/groups/gitlab-org/-/epics/10624) is proposed. - -## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta). - -To enable Code Suggestions on a self-managed GitLab EE instance, you must: - -- Be an administrator. -- Have a [GitLab SaaS account](https://gitlab.com/users/sign_up). -You do not need to have a GitLab SaaS subscription. - -Then, you will: - -1. Enable Code Suggestions for your SaaS account. -1. Enable Code Suggestions for the instance. -1. [Request early access](#request-access-to-code-suggestions) to the Code Suggestions Beta. - -### Enable Code Suggestions for your SaaS account - -To enable Code Suggestions for your GitLab SaaS account: - -1. Create a [personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) - with the `api` scope. -1. On the left sidebar, select your avatar. -1. Select **Preferences**. -1. In the **Code Suggestions** section, select **Enable Code Suggestions**. -1. Select **Save changes**. - -### Enable Code Suggestions for the instance - -You must enable Code Suggestions for the instance. When you do this, you: - -- Agree to the [GitLab testing agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). -- Acknowledge that GitLab: - - Sends data from the instance, including personal data, to GitLab.com infrastructure. - -To enable Code Suggestions for your self-managed GitLab instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. -1. Expand **Code Suggestions** and: - - Select **Turn on Code Suggestions for this instance**. - - In **Personal access token**, enter your GitLab SaaS personal access token. -1. Select **Save changes**. - -This setting is visible only in self-managed GitLab instances. - -WARNING: -If you clear the **Turn on code suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires. - -### Request access to Code Suggestions - -GitLab provisions access on a customer-by-customer basis for Code Suggestions -on self-managed instances. To request access: - -1. Sign into your GitLab SaaS account. -1. Comment on [issue 415393](https://gitlab.com/gitlab-org/gitlab/-/issues/415393) - and tag your customer success manager. - -After GitLab has provisioned access to Code Suggestions for your instance, -the users in your instance can now enable Code Suggestions. - -## Use Code Suggestions - -Prerequisites: - -- For self-managed GitLab, Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). -- For GitLab SaaS, Code Suggestions must be enabled [for the top-level group](../../group/manage.md#enable-code-suggestions) and [for your user account](#enable-code-suggestions-for-an-individual-user). -- Install and configure a [supported IDE editor extension](#supported-editor-extensions). -To use Code Suggestions: - -1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: - - - Provides entire code snippets, like generating functions. - - Completes the current line. - -1. To accept a suggestion, press <kbd>Tab</kbd>. - -Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. - -GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. - -This feature is currently in [Beta](../../../policy/experiment-beta-support.md#beta). -Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to -mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. - -## Code Suggestions data usage - -Code Suggestions is a generative artificial intelligence (AI) model. - -Your personal access token enables a secure API connection to GitLab.com. -This API connection securely transmits a context window from your IDE/editor to the Code Suggestions GitLab hosted service which calls Google Vertex AI Codey APIs, -and the generated suggestion is transmitted back to your IDE/editor. - -GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview). - -### Data privacy - -No new additional data is collected to enable this feature. Private non-public GitLab customer data is -not used as training data. - -Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) - -### Inference window context - -Code Suggestions currently inferences against the currently opened file and has a context window of 2,048 tokens and 8,192 character limits. This limit includes content before and after the cursor, the file name, and the extension type. -Learn more about Google Vertex AI [code-gecko](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). - -The maximum number of tokens that is generated in the response is default 64. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. -Learn more about Google Vertex AI [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion). - -### Self-managed instance data privacy - -A self-managed GitLab instance does not generate the code suggestion. After successful -authentication to the self-managed instance, a token is generated. - -The IDE/editor then uses this token to securely transmit data directly to -GitLab.com's Code Suggestions service for processing. - -The Code Suggestion service then securely returns an AI-generated code suggestion. - -Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than -what is sent to generate the code suggestion. - -### Training data - -Code suggestions are routed through Google Vertex AI Codey APIs. Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) and [Responsible AI](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/responsible-ai). - -Google Vertex AI Codey APIs are not trained on private non-public GitLab customer or user data. - -Google has [shared the following](https://ai.google/discover/foundation-models/) about the data Codey models are trained on: - -> Codey is our family of foundational coding models built on PaLM 2. Codey was fine-tuned on a large dataset of high quality, permissively licensed code from external sources - -## Progressive enhancement - -This feature is designed as a progressive enhancement to developer's IDEs. -Code Suggestions offer a completion if the machine learning engine can generate a recommendation. -In the event of a connection issue or model inference failure, the feature gracefully degrades. -Code Suggestions do not prevent you from writing code in your IDE. - -### Internet connectivity - -Code Suggestions does not work with offline environments. - -To use Code Suggestions: - -- On GitLab.com, you must have an internet connection and be able to access GitLab. -- In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. - -### Model accuracy and quality - -Code Suggestions can generate low-quality, incomplete, and possibly insecure code. -We strongly encourage all beta users to leverage GitLab native -[Code Quality Scanning](../../../ci/testing/code_quality.md) and -[Security Scanning](../../application_security/index.md) capabilities. - -GitLab currently does not retrain Google Vertex AI Codey APIs. GitLab makes no claims -to the accuracy or quality of code suggestions generated by Google Vertex AI Codey API. -Read more about [Google Vertex AI foundation model capabilities](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). - -## Known limitations - -While in Beta, we are working on improving the accuracy of overall generated content. -However, Code Suggestions may generate suggestions that are: - -- Low-quality -- Incomplete -- Produce failed pipelines -- Insecure code -- Offensive or insensitive - -We are also aware of specific situations that can produce unexpected or incoherent results including: - -- Suggestions written in the middle of existing functions, or "fill in the middle." -- Suggestions based on natural language code comments. -- Suggestions that mixed programming languages in unexpected ways. - -## Feedback - -Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). - -## Troubleshooting - -### Code Suggestions aren't displayed - -If Code Suggestions are not displayed, try the following troubleshooting steps. - -In GitLab, ensure Code Suggestions is enabled: - -- [For your user account](#enable-code-suggestions-for-an-individual-user). -- [For *all* top-level groups your account belongs to](../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. - -To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. - -#### Code Suggestions not displayed in VS Code or GitLab WebIDE - -Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. - -If you are a self-managed user, ensure that Code Suggestions for the [GitLab WebIDE](../../project/web_ide/index.md) are enabled. The same settings apply to VS Code as local IDE. - -1. On the left sidebar, select **Extensions > GitLab Workflow**. -1. Select **Settings** (**{settings}**), and then select **Extension Settings**. -1. In **GitLab > AI Assisted Code Suggestions**, select the **Enable code completion (Beta)** - checkbox. - -If the settings are enabled, but Code Suggestions are still not displayed, try the following steps: - -1. Enable the `Debug` checkbox in the GitLab Workflow **Extension Settings**. -1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Workflow** as the log filter. The command palette command is `GitLab: Show Extension Logs`. -1. Disable and re-enable the **Enable code completion (Beta)** checkbox. -1. Verify that the debug log contains similar output: - -```shell -2023-07-14T17:29:00:763 [debug]: Disabling code completion -2023-07-14T17:29:01:802 [debug]: Enabling code completion -2023-07-14T17:29:01:802 [debug]: AI Assist: Using server: https://codesuggestions.gitlab.com/v2/completions -``` - -#### Code Suggestions not displayed in Microsoft Visual Studio - -Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. - -1. Ensure you have properly [set up the extension](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension#setup). -1. From the **Tools > Options** menu, find the **GitLab** option. Ensure **Log Level** is set to **Debug**. -1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Extension** as the log filter. -1. Verify that the debug log contains similar output: - -```shell -14:48:21:344 GitlabProposalSource.GetCodeSuggestionAsync -14:48:21:344 LsClient.SendTextDocumentCompletionAsync("GitLab.Extension.Test\TestData.cs", 34, 0) -14:48:21:346 LS(55096): time="2023-07-17T14:48:21-05:00" level=info msg="update context" -``` - -### Authentication troubleshooting - -If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, -specifically the token system. To resolve the issue: - -1. Remove the existing personal access token from your GitLab account settings. -1. Reauthorize your GitLab account in VS Code using OAuth. -1. Test the code suggestions feature with different file extensions to verify if the issue is resolved. diff --git a/doc/user/project/repository/code_suggestions/index.md b/doc/user/project/repository/code_suggestions/index.md new file mode 100644 index 00000000000..4f0c0b2c9a6 --- /dev/null +++ b/doc/user/project/repository/code_suggestions/index.md @@ -0,0 +1,192 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions **(FREE ALL BETA)** + +> - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. +> - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. + +WARNING: +This feature is in [Beta](../../../../policy/experiment-beta-support.md#beta). +Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your [feedback](#feedback). + +Write code more efficiently by using generative AI to suggest code while you're developing. + +GitLab Duo Code Suggestions are available: + +- On [self-managed](self_managed.md) and [SaaS](saas.md). +- In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. +- In the GitLab WebIDE. + +<div class="video-fallback"> + <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">View an end-to-end demo of Code Suggestions in VS Code</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> +</figure> + +Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). + +## Supported languages + +The best results from Code Suggestions are expected [for languages the Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_coding_languages) directly support: + +- C++ +- C# +- Go +- Google SQL +- Java +- JavaScript +- Kotlin +- PHP +- Python +- Ruby +- Rust +- Scala +- Swift +- TypeScript + +### Supported code infrastructure interfaces + +Code Suggestions includes [Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) support for the following infrastructure as code interfaces: + +- Google Cloud CLI +- Kubernetes Resource Model (KRM) +- Terraform + +Suggestion quality for other languages and using natural language code comments to request completions may not yet result in high-quality suggestions. + +### Supported languages in IDEs + +Editor support for languages is documented in the following table. + +| Language | VS Code | JetBrains IDEs | Visual Studio | Neovim | +|------------------|------------------------|------------------------|------------------------|--------| +| C++ | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | +| C# | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Go | **{check-circle}** Yes | **{check-circle}** Yes (IDEA Ultimate / GoLand) | **{check-circle}** Yes | **{check-circle}** Yes | +| Google SQL | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | **{check-circle}** Yes | +| Java | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| JavaScript | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Kotlin | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| PHP | **{check-circle}** Yes | **{check-circle}** Yes (IDEA Ultimate) | **{check-circle}** Yes | **{check-circle}** Yes | +| Python | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Ruby | **{check-circle}** Yes | **{check-circle}** Yes (IDEA Ultimate / RubyMine) | **{check-circle}** Yes | **{check-circle}** Yes | +| Rust | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Scala | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Swift | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| TypeScript | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Google Cloud | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | +| Kubernetes Resource Model (KRM) | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | +| Terraform | **{check-circle}** Yes (Requires third-party extension providing Terraform support) | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes (Requires third-party extension providing the `terraform` file type) | + +## Supported editor extensions + +Code Suggestions supports a variety of popular editors including: + +- VS Code, using [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). +- [GitLab WebIDE (VS Code in the Cloud)](../../../project/web_ide/index.md), with no additional configuration. +- Microsoft Visual Studio, using the [Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). +- JetBrains IDEs, using the [GitLab plugin](https://plugins.jetbrains.com/plugin/22325-gitlab). +- Neovim, using the [`gitlab.vim` plugin](https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim). + +A [GitLab Language Server for Code Suggestions](https://gitlab.com/gitlab-org/editor-extensions/gitlab-language-server-for-code-suggestions) +is also in process. +This improvement should result in: + +- Faster iteration and standardization of the IDE extensions. +- The ability to use Code Suggestions even when an official editor extension isn't available. + +## Code Suggestions data usage + +Code Suggestions is a generative artificial intelligence (AI) model. + +Your personal access token enables a secure API connection to GitLab.com. +This API connection securely transmits a context window from your IDE/editor to the Code Suggestions GitLab hosted service which calls Google Vertex AI Codey APIs, +and the generated suggestion is transmitted back to your IDE/editor. + +GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview). Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance). + +### Telemetry + +For self-managed instances that have enabled Code Suggestions and SaaS accounts, we collect aggregated or de-identified first-party usage data through our [Snowplow collector](https://about.gitlab.com/handbook/business-technology/data-team/platform/snowplow/). This usage data includes the following metrics: + +- Language the code suggestion was in (for example, Python) +- Editor being used (for example, VS Code) +- Number of suggestions shown, accepted, rejected, or that had errors +- Duration of time that a suggestion was shown +- Prompt and suffix lengths +- Model used +- Number of unique users +- Number of unique instances + +### Inference window context + +Code Suggestions currently inferences against the currently opened file and has a context window of 2,048 tokens and 8,192 character limits. This limit includes content before and after the cursor, the file name, and the extension type. +Learn more about Google Vertex AI [code-gecko](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). + +The maximum number of tokens that is generated in the response is default 64. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words. +Learn more about Google Vertex AI [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion). + +### Training data + +Code Suggestions are routed through Google Vertex AI Codey APIs. Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) and [Responsible AI](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/responsible-ai). + +Google Vertex AI Codey APIs are not trained on private non-public GitLab customer or user data. + +Google has [shared the following](https://ai.google/discover/foundation-models/) about the data Codey models are trained on: + +> Codey is our family of foundational coding models built on PaLM 2. Codey was fine-tuned on a large dataset of high quality, permissively licensed code from external sources + +## Progressive enhancement + +This feature is designed as a progressive enhancement to developer's IDEs. +Code Suggestions offer a completion if the machine learning engine can generate a recommendation. +In the event of a connection issue or model inference failure, the feature gracefully degrades. +Code Suggestions do not prevent you from writing code in your IDE. + +### Internet connectivity + +Code Suggestions does not work with offline environments. + +To use Code Suggestions: + +- On GitLab.com, you must have an internet connection and be able to access GitLab. +- In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. + +### Model accuracy and quality + +Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +We strongly encourage all beta users to leverage GitLab native +[Code Quality Scanning](../../../../ci/testing/code_quality.md) and +[Security Scanning](../../../application_security/index.md) capabilities. + +GitLab currently does not retrain Google Vertex AI Codey APIs. GitLab makes no claims +to the accuracy or quality of Code Suggestions generated by Google Vertex AI Codey API. +Read more about [Google Vertex AI foundation model capabilities](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). + +## Known limitations + +While in Beta, we are working on improving the accuracy of overall generated content. +However, Code Suggestions may generate suggestions that are: + +- Low-quality +- Incomplete +- Produce failed pipelines +- Insecure code +- Offensive or insensitive + +We are also aware of specific situations that can produce unexpected or incoherent results including: + +- Suggestions written in the middle of existing functions, or "fill in the middle." +- Suggestions based on natural language code comments. +- Suggestions that mixed programming languages in unexpected ways. + +## Feedback + +Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/code_suggestions/saas.md b/doc/user/project/repository/code_suggestions/saas.md new file mode 100644 index 00000000000..174c227b6fe --- /dev/null +++ b/doc/user/project/repository/code_suggestions/saas.md @@ -0,0 +1,54 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions on GitLab SaaS **(FREE SAAS BETA)** + +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](../../../../policy/experiment-beta-support.md#beta) for early access Ultimate customers on GitLab.com. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1. + +Write code more efficiently by using generative AI to suggest code while you're developing. + +Usage of GitLab Duo Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +Learn about [data usage when using Code Suggestions](index.md#code-suggestions-data-usage). + +## Enable Code Suggestions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). + +You can enable Code Suggestions for an individual or group: + +- [Enable Code Suggestions for all group members](../../../group/manage.md#enable-code-suggestions). (You must be a group owner). +- [Enable Code Suggestions for your own account](../../../profile/preferences.md#enable-code-suggestions). + +The group setting takes precedence over the user setting. + +## Use Code Suggestions + +Prerequisites: + +- Ensure Code Suggestions is enabled for your user and group. +- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). + +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: + + - Provides entire code snippets, like generating functions. + - Completes the current line. + +1. To accept a suggestion, press <kbd>Tab</kbd>. + +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. + +GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. + +This feature is currently in [Beta](../../../../policy/experiment-beta-support.md#beta). +Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. diff --git a/doc/user/project/repository/code_suggestions/self_managed.md b/doc/user/project/repository/code_suggestions/self_managed.md new file mode 100644 index 00000000000..3c149604086 --- /dev/null +++ b/doc/user/project/repository/code_suggestions/self_managed.md @@ -0,0 +1,187 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions on self-managed GitLab **(PREMIUM SELF BETA)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta) on self-managed GitLab. +> - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. +> - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. +> - Code Suggestions in the GitLab WebIDE enabled for all GitLab-hosted customers. + +Write code more efficiently by using generative AI to suggest code while you're developing. + +GitLab Duo Code Suggestions are available on GitLab Enterprise Edition. +Cloud licensing is required for Premium and Ultimate subscription tiers. + +Code Suggestions are not available for GitLab Community Edition. + +WARNING: +In GitLab 16.3 and later, only Premium and Ultimate customers can participate in the free trial of Code Suggestions on self-managed GitLab. + +Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +Learn about [data usage when using Code Suggestions](index.md#code-suggestions-data-usage). + +## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). + +When you enable Code Suggestions for your self-managed instance, you: + +- Agree to the [GitLab testing agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +- Acknowledge that GitLab sends data from the instance, including personal data, to GitLab.com infrastructure. + +How you enable Code Suggestions differs depending on your version of GitLab. + +### GitLab 16.3 and later + +Prerequisites: + +- You are a new Code Suggestions customer as of GitLab 16.3. +- All of the users in your instance have the latest version of their IDE extension. +- You are an administrator. + +To enable Code Suggestions for your self-managed GitLab instance: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Code Suggestions** and select **Turn on Code Suggestions for this instance**. + In GitLab 16.3, you do not need to enter anything into the **Personal access token** field. + In GitLab 16.4 and later, there is no **Personal access token** field. +1. Select **Save changes**. + +This setting is visible only in self-managed GitLab instances. + +WARNING: +In GitLab 16.2 and earlier, if you clear the **Turn on Code Suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires. + +To make sure Code Suggestions works immediately, you must [manually synchronize your subscription](#manually-synchronize-your-subscription). + +The users in your instance can now use Code Suggestions. + +### GitLab 16.2 and earlier + +Prerequisites: + +- You are an administrator. +- You have a [customer success manager](https://about.gitlab.com/handbook/customer-success/csm/]). +- You have a [GitLab SaaS account](https://gitlab.com/users/sign_up). You do not need to have a GitLab SaaS subscription. + +NOTE: +If you do not have a customer success manager, you cannot participate in the free trial of Code Suggestions on self-managed GitLab. Upgrade to GitLab 16.3 to [perform self-service onboarding](#gitlab-163-and-later). + +Then, you will: + +1. Enable Code Suggestions for your SaaS account. +1. Enable Code Suggestions for the instance. +1. [Request early access](#request-access-to-code-suggestions) to the Code Suggestions Beta. + +#### Enable Code Suggestions for your SaaS account + +To enable Code Suggestions for your GitLab SaaS account: + +1. Create a [personal access token](../../../profile/personal_access_tokens.md#create-a-personal-access-token) + with the `api` scope. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Code Suggestions** section, select **Enable Code Suggestions**. +1. Select **Save changes**. + +#### Enable Code Suggestions for the instance + +To enable Code Suggestions for your self-managed GitLab instance: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Code Suggestions** and: + - Select **Turn on Code Suggestions for this instance**. + - In **Personal access token**, enter your GitLab SaaS personal access token. +1. Select **Save changes**. + +This setting is visible only in self-managed GitLab instances. + +WARNING: +If you clear the **Turn on Code Suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires. + +#### Request access to Code Suggestions + +GitLab provisions access on a customer-by-customer basis for Code Suggestions +on self-managed instances. To request access, contact your customer success manager. + +Your customer success manager then provisions access by commenting on [issue 415393](https://gitlab.com/gitlab-org/gitlab/-/issues/415393) (internal access only). + +After GitLab has provisioned access to Code Suggestions for your instance, +the users in your instance can now enable Code Suggestions. + +### Configure network and proxy settings + +Configure any firewalls to allow outbound connections to `https://codesuggestions.gitlab.com/`. + +If your GitLab instance uses an HTTP proxy server to access the internet, ensure +the server is configured to allow outbound connections, including the +[`gitlab_workhorse` environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html). + +### Update GitLab + +In GitLab 16.3 and later, GitLab is enforcing the cloud licensing requirement for Code Suggestions: + +- The Premium and Ultimate subscription tiers support cloud Licensing. +- GitLab Free does not have cloud licensing support. + +If you have a GitLab Free subscription and update to GitLab 16.3 or later, +to continue having early access to Code Suggestions, you must: + +1. Have a [subscription that supports cloud licensing](https://about.gitlab.com/pricing/). +1. Make sure you have the latest version of your [IDE extension](index.md#supported-editor-extensions). +1. [Manually synchronize your subscription](#manually-synchronize-your-subscription). + +#### Manually synchronize your subscription + +You must [manually synchronize your subscription](../../../../subscriptions/self_managed/index.md#manually-synchronize-your-subscription-details) if either: + +- You have already updated to GitLab 16.3 and have just bought a Premium or Ultimate tier subscription. +- You already have a Premium or Ultimate tier subscription and have just updated to GitLab 16.3. + +Without the manual synchronization, it might take up to 24 hours to active Code Suggestions on your instance. + +## Use Code Suggestions + +Prerequisites: + +- Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). +- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). + +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: + + - Provides entire code snippets, like generating functions. + - Completes the current line. + +1. To accept a suggestion, press <kbd>Tab</kbd>. + +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. + +GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. + +This feature is currently in [Beta](../../../../policy/experiment-beta-support.md#beta). +Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + +### Data privacy + +A self-managed GitLab instance does not generate the code suggestion. After successful +authentication to the self-managed instance, a token is generated. + +The IDE/editor then uses this token to securely transmit data directly to +GitLab.com's Code Suggestions service for processing. + +The Code Suggestions service then securely returns an AI-generated code suggestion. + +Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than +what is sent to generate the code suggestion. diff --git a/doc/user/project/repository/code_suggestions/troubleshooting.md b/doc/user/project/repository/code_suggestions/troubleshooting.md new file mode 100644 index 00000000000..c0cdb3cc32d --- /dev/null +++ b/doc/user/project/repository/code_suggestions/troubleshooting.md @@ -0,0 +1,69 @@ +--- +stage: Create +group: Code Creation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Troubleshooting Code Suggestions **(FREE ALL BETA)** + +When working with GitLab Duo Code Suggestions, you might encounter the following issues. + +## Code Suggestions aren't displayed + +If Code Suggestions are not displayed, try the following troubleshooting steps. + +In GitLab, ensure Code Suggestions is enabled: + +- [For your user account](../../../profile/preferences.md#enable-code-suggestions). +- [For *all* top-level groups your account belongs to](../../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. + +To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. + +### Code Suggestions not displayed in VS Code or GitLab WebIDE + +Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. + +If you are a self-managed user, ensure that Code Suggestions for the [GitLab WebIDE](../../../project/web_ide/index.md) are enabled. The same settings apply to VS Code as local IDE. + +1. On the left sidebar, select **Extensions > GitLab Workflow**. +1. Select **Settings** (**{settings}**), and then select **Extension Settings**. +1. In **GitLab > AI Assisted Code Suggestions**, select the **Enable code completion (Beta)** + checkbox. + +If the settings are enabled, but Code Suggestions are still not displayed, try the following steps: + +1. Enable the `Debug` checkbox in the GitLab Workflow **Extension Settings**. +1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Workflow** as the log filter. The command palette command is `GitLab: Show Extension Logs`. +1. Disable and re-enable the **Enable code completion (Beta)** checkbox. +1. Verify that the debug log contains similar output: + +```shell +2023-07-14T17:29:00:763 [debug]: Disabling code completion +2023-07-14T17:29:01:802 [debug]: Enabling code completion +2023-07-14T17:29:01:802 [debug]: AI Assist: Using server: https://codesuggestions.gitlab.com/v2/completions +``` + +### Code Suggestions not displayed in Microsoft Visual Studio + +Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. + +1. Ensure you have properly [set up the extension](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension#setup). +1. From the **Tools > Options** menu, find the **GitLab** option. Ensure **Log Level** is set to **Debug**. +1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Extension** as the log filter. +1. Verify that the debug log contains similar output: + +```shell +14:48:21:344 GitlabProposalSource.GetCodeSuggestionAsync +14:48:21:344 LsClient.SendTextDocumentCompletionAsync("GitLab.Extension.Test\TestData.cs", 34, 0) +14:48:21:346 LS(55096): time="2023-07-17T14:48:21-05:00" level=info msg="update context" +``` + +## Authentication troubleshooting + +If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, +specifically the token system. To resolve the issue: + +1. Remove the existing personal access token from your GitLab account settings. +1. Reauthorize your GitLab account in VS Code using OAuth. +1. Test the Code Suggestions feature with different file extensions to verify if the issue is resolved. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index ee2be6dee7c..5dd8ad39889 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -14,7 +14,7 @@ File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fu To search for a file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. In the upper right, select **Find file**. 1. In the search box, start typing the filename. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 4c37b92b388..a304a8d108d 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -59,8 +59,8 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates To update your fork from the GitLab UI: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. Select the fork you want to update. 1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**) information box to determine if your fork is ahead, behind, or both. In this example, @@ -181,13 +181,13 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To remove a fork relationship: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Remove fork relationship** section, select **Remove fork relationship**. 1. To confirm, enter the project path and select **Confirm**. -When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_types.md#hashed-object-pools) +When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_paths.md#hashed-object-pools) to share objects with another repository: - All objects are copied from the pool into your fork. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 8bb6d868270..592041ef4e2 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,330 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../signed_commits/gpg.md' +remove_date: '2023-12-01' --- -# Sign commits with GPG **(FREE ALL)** +This document was moved to [another location](../signed_commits/gpg.md). -You can sign the commits you make in a GitLab repository with a -GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic -signature to your commit, you provide extra assurance that a commit -originated from you, rather than an impersonator. If GitLab can verify a commit -author's identity with a public GPG key, the commit is marked **Verified** in the -GitLab UI. You can then configure [push rules](../push_rules.md) -for your project to reject individual commits not signed with GPG, or reject all -commits from unverified users. - -NOTE: -GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and -implementations. - -For GitLab to consider a commit verified: - -- The committer must have a GPG public/private key pair. -- The committer's public key must be uploaded to their GitLab account. -- One of the email addresses in the GPG public key must match a **verified** email address - used by the committer in GitLab. To keep this address private, use the automatically generated - [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) - GitLab provides in your profile. -- The committer's email address must match the verified email address from the - GPG key. - -GitLab uses its own keyring to verify the GPG signature. It does not access any -public key server. - -GPG verified tags are not supported. - -For more details about GPG, refer to the [related topics list](#related-topics). - -## View a user's public GPG key - -To view a user's public GPG key, you can either: - -- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, - if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner - of the user's profile, select **View public GPG keys** (**{key}**). - -## Configure commit signing - -To sign commits, you must configure both your local machine and your GitLab account: - -1. [Create a GPG key](#create-a-gpg-key). -1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). -1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). -1. [Sign your Git commits](#sign-your-git-commits). - -### Create a GPG key - -If you don't already have a GPG key, create one: - -1. [Install GPG](https://www.gnupg.org/download/) for your operating system. - If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in - the commands on this page. -1. To generate your key pair, run the command appropriate for your version of `gpg`: - - ```shell - # Use this command for the default version of GPG, including - # Gpg4win on Windows, and most macOS versions: - gpg --gen-key - - # Use this command for versions of GPG later than 2.1.17: - gpg --full-gen-key - ``` - -1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select - the default option, `RSA and RSA`. -1. Select the key length, in bits. GitLab recommends 4096-bit keys. -1. Specify the validity period of your key. This value is subjective, and the - default value is no expiration. -1. To confirm your answers, enter `y`. -1. Enter your name. -1. Enter your email address. It must match a - [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) - in your GitLab account. -1. Optional. Enter a comment to display in parentheses after your name. -1. GPG displays the information you've entered so far. Edit the information or press - <kbd>O</kbd> (for `Okay`) to continue. -1. Enter a strong password, then enter it again to confirm it. -1. To list your private GPG key, run this command, replacing - `<EMAIL>` with the email address you used when you generated the key: - - ```shell - gpg --list-secret-keys --keyid-format LONG <EMAIL> - ``` - -1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after - the `/` character. In this example, the key ID is `30F2B65B9246B6CA`: - - ```plaintext - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` - -1. To show the associated public key, run this command, replacing `<ID>` with the - GPG key ID from the previous step: - - ```shell - gpg --armor --export <ID> - ``` - -1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and - `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step. - -### Add a GPG key to your account - -To add a GPG key to your user settings: - -1. Sign in to GitLab. -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. Select **GPG Keys** (**{key}**). -1. Select **Add new key**. -1. In **Key**, paste your _public_ key. -1. To add the key to your account, select **Add key**. GitLab shows the key's - fingerprint, email address, and creation date: - -  - -After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. - -### Associate your GPG key with Git - -After you [create your GPG key](#create-a-gpg-key) and -[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git -to use this key: - -1. Run this command to list the private GPG key you just created, - replacing `<EMAIL>` with the email address for your key: - - ```shell - gpg --list-secret-keys --keyid-format LONG <EMAIL> - ``` - -1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is - `30F2B65B9246B6CA`: - - ```plaintext - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` - -1. Run this command to configure Git to sign your commits with your key, - replacing `<KEY ID>` with your GPG key ID: - - ```shell - git config --global user.signingkey <KEY ID> - ``` - -### Sign your Git commits - -After you [add your public key to your account](#add-a-gpg-key-to-your-account), -you can sign individual commits manually, or configure Git to default to signed commits: - -- Sign individual Git commits manually: - 1. Add `-S` flag to any commit you want to sign: - - ```shell - git commit -S -m "My commit message" - ``` - - 1. Enter the passphrase of your GPG key when asked. - 1. Push to GitLab and check that your commits [are verified](#verify-commits). -- Sign all Git commits by default by running this command: - - ```shell - git config --global commit.gpgsign true - ``` - -#### Set signing key conditionally - -If you maintain signing keys for separate purposes, such as work and personal -use, use an `IncludeIf` statement in your `.gitconfig` file to set which key -you sign commits with. - -Prerequisites: - -- Requires Git version 2.13 or later. - -1. In the same directory as your main `~/.gitconfig` file, create a second file, - such as `.gitconfig-gitlab`. -1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. -1. Append this information to the end of your main `~/.gitconfig` file: - - ```ini - # The contents of this file are included only for GitLab.com URLs - [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] - - # Edit this line to point to your alternate configuration file - path = ~/.gitconfig-gitlab - ``` - -1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to - use when you're committing to a GitLab repository. All settings from your - main `~/.gitconfig` file are retained unless you explicitly override them. - In this example, - - ```ini - # Alternate ~/.gitconfig-gitlab file - # These values are used for repositories matching the string 'gitlab.com', - # and override their corresponding values in ~/.gitconfig - - [user] - email = you@example.com - signingkey = <KEY ID> - - [commit] - gpgsign = true - ``` - -## Verify commits - -You can review commits for a merge request, or for an entire project: - -1. To review commits for a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Commits**. -1. To review commits for a merge request: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Merge requests**, then select your merge request. - 1. Select **Commits**. -1. Identify the commit you want to review. Signed commits show either a **Verified** - or **Unverified** badge, depending on the verification status of the GPG - signature. Unsigned commits do not display a badge: - -  - -1. To display the signature details for a commit, select the GPG badge: - -  - -  - -## Revoke a GPG key - -If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: - -- Past commits signed by this key are marked as unverified. -- Future commits signed by this key are marked as unverified. - -To revoke a GPG key: - -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. Select **GPG Keys** (**{key}**). -1. Select **Revoke** next to the GPG key you want to delete. - -## Remove a GPG key - -When you remove a GPG key from your GitLab account: - -- Previous commits signed with this key remain verified. -- Future commits (including any commits created but not yet pushed) that attempt - to use this key are unverified. - -To remove a GPG key from your account: - -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. Select **GPG Keys** (**{key}**). -1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. - -If you must unverify both future and past commits, -[revoke the associated GPG key](#revoke-a-gpg-key) instead. - -## Related topics - -- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) -- [Sign commits with SSH keys](../ssh_signed_commits/index.md) -- [Commits API](../../../../api/commits.md) -- GPG resources: - - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) - - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) - - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) - - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) - - [Review existing GPG keys in your instance](../../../../administration/credentials_inventory.md#review-existing-gpg-keys) - -## Troubleshooting - -### Fix verification problems with signed commits - -Commits can be signed with [X.509 certificates](../x509_signed_commits/index.md) -or a GPG key. The verification process for both methods can fail for multiple reasons: - -| Value | Description | Possible Fixes | -|-----------------------------|-------------|----------------| -| `UNVERIFIED` | The commit signature is not valid. | Sign the commit with a valid signature. | -| `SAME_USER_DIFFERENT_EMAIL` | The GPG key used to sign the commit does not contain the committer email, but does contain a different valid email for the committer. | Amend the commit to use an email address that matches the GPG key, or update the GPG key [to include the email address](https://security.stackexchange.com/a/261468). | -| `OTHER_USER` | The signature and GPG key are valid, but the key belongs to a different user than the committer. | Amend the commit to use the correct email address, or amend the commit to use a GPG key associated with your user. | -| `UNVERIFIED_KEY` | The key associated with the GPG signature has no verified email address associated with the committer. | Add and verify the email to your GitLab profile, [update the GPG key to include the email address](https://security.stackexchange.com/a/261468), or amend the commit to use a different committer email address. | -| `UNKNOWN_KEY` | The GPG key associated with the GPG signature for this commit is unknown to GitLab. | [Add the GPG key](#add-a-gpg-key-to-your-account) to your GitLab profile. | -| `MULTIPLE_SIGNATURES` | Multiple GPG or X.509 signatures have been found for the commit. | Amend the commit to use only one GPG or X.509 signature. | - -### Secret key not available - -If you receive the errors `secret key not available` -or `gpg: signing failed: secret key not available`, try using `gpg2` instead of `gpg`: - -```shell -git config --global gpg.program gpg2 -``` - -If your GPG key is password protected and the password entry prompt does not appear, -add `export GPG_TTY=$(tty)` to your shell's `rc` file (commonly `~/.bashrc` or `~/.zshrc`) - -### GPG failed to sign the data - -If your GPG key is password protected and you receive the error: - -```shell -error: gpg failed to sign the data -fatal: failed to write commit object -``` - -If the password entry prompt does not appear, add `export GPG_TTY=$(tty)` to your shell's `rc` file -(commonly `~/.bashrc` or `~/.zshrc`) and restart your terminal. +<!-- This redirect file can be deleted after <2023-12-01>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 3d00ceafc05..e97892458b4 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -55,7 +55,7 @@ to a branch in the repository. When you use the command line, you can commit mul [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) from the UI to a selected branch. - **Sign a commit:** - Use GPG to [sign your commits](gpg_signed_commits/index.md). + Add extra security by [signing your commits](signed_commits/index.md). ## Clone a repository @@ -73,7 +73,7 @@ into Xcode on macOS. 1. Select **Xcode**. The project is cloned onto your computer and you are -prompted to open XCode. +prompted to open Xcode. ### Clone and open in Visual Studio Code @@ -216,6 +216,11 @@ To render an OpenAPI file: 1. Go to the OpenAPI file in your repository. 1. Between the **Display source** and **Edit** buttons, select **Display OpenAPI**. When an OpenAPI file is found, it replaces the **Display rendered file** button. +1. To display the `operationId` in the operations list, add `displayOperationId=true` to the query string. + +NOTE: +When `displayOperationId` is present in the query string and has _any_ value, it +evaluates to `true`. This behavior matches the default behavior of Swagger. ## Repository size diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 70ee841a991..2a1fc0cddf8 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -37,7 +37,7 @@ When commits include changes to Jupyter Notebook files, GitLab: - Enables switching between raw and rendered diffs on the Commit and Compare pages. (Not available on merge request pages.) - Renders images on the diffs. -Code suggestions are not available on diffs and merge requests for `.ipynb` files. +Code Suggestions are not available on diffs and merge requests for `.ipynb` files. Cleaner notebook diffs are not generated when the notebook is too large. diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index e5c1e4a6614..1d5127b5e08 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -1,53 +1,411 @@ --- stage: Systems -group: Distribution +group: Gitaly info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -description: "Documentation on large repositories." --- -# Managing large repositories **(FREE SELF)** +# Managing monorepos -GitLab, like any Git based system, is subject to similar performance restraints when it comes to large -repositories that size into the gigabytes. +Monorepos have become a regular part of development team workflows. While they have many advantages, monorepos can present performance challenges +when using them in GitLab. Therefore, you should know: -In the following sections, we detail several best practices for improving performance with these large repositories on GitLab. +- What repository characteristics can impact performance. +- Some tools and steps to optimize monorepos. -## Large File System (LFS) +## Impact on performance -It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, or graphics) are stored as Large File Storage (LFS) objects. With LFS, the objects are stored externally, such as in Object Storage, which reduces the number and size of objects in the repository. Storing objects in external Object Storage can improve performance. +Because GitLab is a Git-based system, it is subject to similar performance +constraints as Git when it comes to large repositories that are gigabytes in +size. -To analyze if a repository has large objects, you can use a tool like [`git-sizer`](https://github.com/github/git-sizer) for detailed analysis. This tool shows details about what makes up the repository, and highlights any areas of concern. If any large objects are found, you can then remove them with a tool such as [`git filter-repo`](reducing_the_repo_size_using_git.md). +Monorepos can be large for [many reasons](https://about.gitlab.com/blog/2022/09/06/speed-up-your-monorepo-workflow-in-git/#characteristics-of-monorepos). + +Large repositories pose a performance risk performance when used in GitLab, especially if a large monorepo receives many clones or pushes a day, which is common for them. + +Git itself has performance limitations when it comes to handling +monorepos. + +[Gitaly](https://gitlab.com/gitlab-org/gitaly) is our Git storage service built +on top of [Git](https://git-scm.com/). This means that any limitations of +Git are experienced in Gitaly, and in turn by end users of GitLab. + +## Profiling repositories + +Large repositories generally experience performance issues in Git. Knowing why +your repository is large can help you develop mitigation strategies to avoid +performance problems. + +You can use [`git-sizer`](https://github.com/github/git-sizer) to get a snapshot +of repository characteristics and discover problem aspects of your monorepo. + +For example: + +```shell +Processing blobs: 1652370 +Processing trees: 3396199 +Processing commits: 722647 +Matching commits to trees: 722647 +Processing annotated tags: 534 +Processing references: 539 +| Name | Value | Level of concern | +| ---------------------------- | --------- | ------------------------------ | +| Overall repository size | | | +| * Commits | | | +| * Count | 723 k | * | +| * Total size | 525 MiB | ** | +| * Trees | | | +| * Count | 3.40 M | ** | +| * Total size | 9.00 GiB | **** | +| * Total tree entries | 264 M | ***** | +| * Blobs | | | +| * Count | 1.65 M | * | +| * Total size | 55.8 GiB | ***** | +| * Annotated tags | | | +| * Count | 534 | | +| * References | | | +| * Count | 539 | | +| | | | +| Biggest objects | | | +| * Commits | | | +| * Maximum size [1] | 72.7 KiB | * | +| * Maximum parents [2] | 66 | ****** | +| * Trees | | | +| * Maximum entries [3] | 1.68 k | * | +| * Blobs | | | +| * Maximum size [4] | 13.5 MiB | * | +| | | | +| History structure | | | +| * Maximum history depth | 136 k | | +| * Maximum tag depth [5] | 1 | | +| | | | +| Biggest checkouts | | | +| * Number of directories [6] | 4.38 k | ** | +| * Maximum path depth [7] | 13 | * | +| * Maximum path length [8] | 134 B | * | +| * Number of files [9] | 62.3 k | * | +| * Total size of files [9] | 747 MiB | | +| * Number of symlinks [10] | 40 | | +| * Number of submodules | 0 | | +``` + +In this example, a few items are raised with a high level of concern. See the +following sections for information on solving: + +- A high number of references. +- Large blobs. + +### Large number of references + +A reference in Git (a branch or tag) is used to refer to a commit. Each +reference is stored as an individual file. If you are curious, you can go +to any `.git` directory and look under the `refs` directory. + +A large number of references can cause performance problems because, with more references, +object walks that Git does are larger for various operations such as clones, pushes, and +housekeeping tasks. + +#### Mitigation strategies + +To mitigate the effects of a large number of references in a monorepo: + +- Create an automated process for cleaning up old branches. +- If certain references don't need to be visible to the client, hide them using the + [`transfer.hideRefs`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-transferhideRefs) + configuration setting. Because Gitaly ignores any on-server Git configuration, you must change the Gitaly configuration + itself in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitaly['configuration'] = { + # ... + git: { + # ... + config: [ + # ... + { key: "transfer.hideRefs", value: "refs/namespace_to_hide" }, + ], + }, + } + ``` + +In Git 2.42.0 and later, different Git operations can skip over hidden references +when doing an object graph walk. + +### Using LFS for large blobs + +Because Git is built to handle text data, it doesn't handle large +binary files efficiently. + +Therefore, you should store binary or blob files (for example, packages, audio, video, or graphics) +as Large File Storage (LFS) objects. With LFS, the objects are stored externally, such as in Object +Storage, which reduces the number and size of objects in the repository. Storing +objects in external Object Storage can improve performance. + +To analyze if a repository has large objects, you can use a tool like +[`git-sizer`](https://github.com/github/git-sizer) for detailed analysis. This +tool shows details about what makes up the repository, and highlights any areas +of concern. If any large objects are found, you can then remove them with a tool +such as [`git filter-repo`](reducing_the_repo_size_using_git.md). For more information, refer to the [Git LFS documentation](../../../topics/git/lfs/index.md). -## Gitaly Pack Objects Cache +## Optimizing large repositories for GitLab + +Other than modifying your workflow and the actual repository, you can take other +steps to maximize performance of monorepos with GitLab. + +### Gitaly pack-objects cache + +For very active repositories with a large number of references and files, consider using the +[Gitaly pack-objects cache](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). +The pack-objects cache: + +- Benefits all repositories on your GitLab server. +- Automatically works for forks. + +You should always: + +- Fetch incrementally. Do not clone in a way that recreates all of the worktree. +- Use shallow clones to reduce data transfer. Be aware that this puts more burden on GitLab instance because of higher CPU impact. + +Control the clone directory if you heavily use a fork-based workflow. Optimize +`git clean` flags to ensure that you remove or keep data that might affect or +speed-up your build. + +For more information, see [Pack-objects cache](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). + +### Reduce concurrent clones in CI/CD + +Large repositories tend to be monorepos. This usually means that these +repositories get a lot of traffic not only from users, but from CI/CD. + +CI/CD loads tend to be concurrent because pipelines are scheduled during set times. +As a result, the Git requests against the repositories can spike notably during +these times and lead to reduced performance for both CI/CD and users alike. + +You should reduce CI/CD pipeline concurrency by staggering them to run at different times. For example, a set running at one time and another set running several +minutes later. + +#### Shallow cloning + +GitLab and GitLab Runner perform a [shallow clone](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone) +by default. + +Ideally, you should always use `GIT_DEPTH` with a small number +like 10. This instructs GitLab Runner to perform shallow clones. +Shallow clones make Git request only the latest set of changes for a given branch, +up to desired number of commits as defined by the `GIT_DEPTH` variable. + +This significantly speeds up fetching of changes from Git repositories, +especially if the repository has a very long backlog consisting of a number +of big files because we effectively reduce amount of data transfer. +The following pipeline configuration example makes the runner shallow clone to fetch only a given branch. +The runner does not fetch any other branches nor tags. + +```yaml +variables: + GIT_DEPTH: 10 + +test: + script: + - ls -al +``` + +#### Git strategy + +By default, GitLab is configured to use the [`fetch` Git strategy](../../../ci/runners/configure_runners.md#git-strategy), +which is recommended for large repositories. +This strategy reduces the amount of data to transfer and +does not really impact the operations that you might do on a repository from CI/CD. + +#### Git clone path + +[`GIT_CLONE_PATH`](../../../ci/runners/configure_runners.md#custom-build-directories) allows you to +control where you clone your repositories. This can have implications if you +heavily use big repositories with a fork-based workflow. + +A fork, from the perspective of GitLab Runner, is stored as a separate repository +with a separate worktree. That means that GitLab Runner cannot optimize the usage +of worktrees and you might have to instruct GitLab Runner to use that. + +In such cases, ideally you want to make the GitLab Runner executor be used only +for the given project and not shared across different projects to make this +process more efficient. + +The [`GIT_CLONE_PATH`](../../../ci/runners/configure_runners.md#custom-build-directories) must be +in the directory set in `$CI_BUILDS_DIR`. You can't pick any path from disk. + +#### Git clean flags + +[`GIT_CLEAN_FLAGS`](../../../ci/runners/configure_runners.md#git-clean-flags) allows you to control +whether or not you require the `git clean` command to be executed for each CI/CD +job. By default, GitLab ensures that: + +- You have your worktree on the given SHA. +- Your repository is clean. + +[`GIT_CLEAN_FLAGS`](../../../ci/runners/configure_runners.md#git-clean-flags) is disabled when set +to `none`. On very big repositories, this might be desired because `git +clean` is disk I/O intensive. Controlling that with `GIT_CLEAN_FLAGS: -ffdx +-e .build/` (for example) allows you to control and disable removal of some +directories in the worktree between subsequent runs, which can speed-up +the incremental builds. This has the biggest effect if you re-use existing +machines and have an existing worktree that you can re-use for builds. + +For exact parameters accepted by +[`GIT_CLEAN_FLAGS`](../../../ci/runners/configure_runners.md#git-clean-flags), see the documentation +for [`git clean`](https://git-scm.com/docs/git-clean). The available parameters +are dependent on the Git version. + +#### Git fetch extra flags + +[`GIT_FETCH_EXTRA_FLAGS`](../../../ci/runners/configure_runners.md#git-fetch-extra-flags) allows you +to modify `git fetch` behavior by passing extra flags. + +For example, if your project contains a large number of tags that your CI/CD jobs don't rely on, +you could add [`--no-tags`](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---no-tags) +to the extra flags to make your fetches faster and more compact. + +Also in the case where you repository does _not_ contain a lot of +tags, `--no-tags` can [make a big difference in some cases](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/746). +If your CI/CD builds do not depend on Git tags, setting `--no-tags` is worth trying. + +For more information, see the [`GIT_FETCH_EXTRA_FLAGS` documentation](../../../ci/runners/configure_runners.md#git-fetch-extra-flags). + +#### Fork-based workflow + +Following the guidelines above, let's imagine that we want to: + +- Optimize for a big project (more than 50k files in directory). +- Use forks-based workflow for contributing. +- Reuse existing worktrees. Have preconfigured runners that are pre-cloned with repositories. +- Runner assigned only to project and all forks. + +Let's consider the following two examples, one using `shell` executor and +other using `docker` executor. + +##### `shell` executor example + +Let's assume that you have the following [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "shell" + builds_dir = "/builds" + cache_dir = "/cache" + + [runners.custom_build_dir] + enabled = true +``` + +This `config.toml`: + +- Uses the `shell` executor, +- Specifies a custom `/builds` directory where all clones are stored. +- Enables the ability to specify `GIT_CLONE_PATH`, +- Runs at most 4 jobs at once. + +##### `docker` executor example + +Let's assume that you have the following [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "docker" + builds_dir = "/builds" + cache_dir = "/cache" + + [runners.docker] + volumes = ["/builds:/builds", "/cache:/cache"] +``` + +This `config.toml`: + +- Uses the `docker` executor, +- Specifies a custom `/builds` directory on disk where all clones are stored. + We host mount the `/builds` directory to make it reusable between subsequent runs + and be allowed to override the cloning strategy. +- Doesn't enable the ability to specify `GIT_CLONE_PATH` as it is enabled by default. +- Runs at most 4 jobs at once. + +##### Our `.gitlab-ci.yml` + +Once we have the executor configured, we need to fine tune our `.gitlab-ci.yml`. + +Our pipeline is most performant if we use the following `.gitlab-ci.yml`: + +```yaml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME + +build: + script: ls -al +``` + +This YAML setting configures a custom clone path. This path makes it possible to re-use worktrees +between the parent project and forks because we use the same clone path for all forks. + +Why use `$CI_CONCURRENT_ID`? The main reason is to ensure that worktrees used are not conflicting +between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor. +When we use it to construct the path, this directory does not conflict +with other concurrent jobs running. + +### Store custom clone options in `config.toml` + +Ideally, all job-related configuration should be stored in `.gitlab-ci.yml`. +However, sometimes it is desirable to make these schemes part of the runner's configuration. -Gitaly, the service that provides storage for Git repositories, can be configured to cache a short rolling window of Git fetch responses. This is recommended for large repositories as it can notably reduce server load when your server receives lots of fetch traffic. +In the above example of forks, making this configuration discoverable for users may be preferred, +but this brings administrative overhead as the `.gitlab-ci.yml` needs to be updated for each branch. +In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agnostic, but make it +a configuration of the runner. -Refer to the [Gitaly Pack Objects Cache for more information](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). +We can extend our [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) +with the following specification that is used by the runner if `.gitlab-ci.yml` does not override it: -## Reference Architectures +```toml +concurrent = 4 -Large repositories tend to be found in larger organisations with many users. The GitLab Quality and Support teams provide several [Reference Architectures](../../../administration/reference_architectures/index.md) that are the recommended way to deploy GitLab at scale. +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "docker" + builds_dir = "/builds" + cache_dir = "/cache" -In these types of setups it's recommended that the GitLab environment used matches a Reference Architecture to improve performance. + environment = [ + "GIT_CLONE_PATH=$CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME" + ] -## Gitaly Cluster + [runners.docker] + volumes = ["/builds:/builds", "/cache:/cache"] +``` -Gitaly Cluster can notably improve large repository performance as it holds multiple replicas of the repository across several nodes. As a result, Gitaly Cluster can load balance read requests against those repositories and is also fault-tolerant. +This makes the cloning configuration to be part of the given runner +and does not require us to update each `.gitlab-ci.yml`. -It's recommended for large repositories, however, Gitaly Cluster is a large solution with additional complexity of setup, and management. Refer to the [Gitaly Cluster documentation for more information](../../../administration/gitaly/index.md), specifically the [Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. +### Reference architectures -## Keep GitLab up to date +Large repositories tend to be found in larger organisations with many users. The GitLab Quality and Support teams provide several [reference architectures](../../../administration/reference_architectures/index.md) that are the recommended way to deploy GitLab at scale. -Performance improvements and fixes are added continuously in GitLab. As such, it's recommended you keep GitLab updated to the latest version where possible to benefit from these. +In these types of setups, the GitLab environment used should match a reference architecture to improve performance. -## Reduce concurrent clones in CI/CD +### Gitaly Cluster -Large repositories tend to be monorepos. This in turn typically means that these repositories get a lot of traffic not only from users, but from CI/CD. +Gitaly Cluster can notably improve large repository performance because it holds multiple replicas of the repository across several nodes. +As a result, Gitaly Cluster can load balance read requests against those replicas and is fault-tolerant. -CI/CD loads tend to be concurrent as pipelines are scheduled during set times. As a result, the Git requests against the repositories can spike notably during these times and lead to reduced performance for both CI and users alike. +Though Gitaly Cluster is recommended for large repositories, it is a large solution with additional complexity of setup and management. Refer to the +[Gitaly Cluster documentation for more information](../../../administration/gitaly/index.md), specifically the +[Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. -When designing CI/CD pipelines, it's advisable to reduce their concurrency by staggering them to run at different times, for example, a set running at one time, and another set running several minutes later. +### Keep GitLab up to date -There's several other actions that can be explored to improve CI/CD performance with large repositories. Refer to the [Runner documentation for more information](../../../ci/large_repositories/index.md). +You should keep GitLab updated to the latest version where possible to benefit from performance improvements and fixes are added continuously to GitLab. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index fade9e1b63c..9d97f53cb43 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -44,7 +44,7 @@ and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 7ade27e556d..b16197e45b2 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -40,7 +40,7 @@ Prerequisites: - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Select **Add new**. @@ -111,7 +111,7 @@ Prerequisite: - You must have at least the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories** and identify the mirror to update. @@ -124,9 +124,8 @@ When you create a mirror, you must configure the authentication method for it. GitLab supports these authentication methods: - [SSH authentication](#ssh-authentication). -- Password. +- Username and password. -When using password authentication, ensure you specify the username. For a [project access token](../../settings/project_access_tokens.md) or [group access token](../../../group/settings/group_access_tokens.md), use the username (not token name) and the token as the password. @@ -154,7 +153,7 @@ When you mirror a repository and select the **SSH public key** as your authentication method, GitLab generates a public key for you. The non-GitLab server needs this key to establish trust with your GitLab repository. To copy your SSH public key: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories**. diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index ba54c18f8ee..5b3c76d982a 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -64,14 +64,13 @@ Prerequisites: token serves as your GitHub password. - [GitLab Silent Mode](../../../../administration/silent_mode/index.md) is not enabled. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. -1. Enter the **Git repository URL**. Include the username - in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` +1. Enter the **Git repository URL**. NOTE: - To mirror the `gitlab` repository, use `git@gitlab.com:gitlab-org/gitlab.git` + To mirror the `gitlab` repository, use `gitlab.com:gitlab-org/gitlab.git` or `https://gitlab.com/gitlab-org/gitlab.git`. 1. In **Mirror direction**, select **Pull**. diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index cd4fe68b01b..e18e3631d7f 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -37,7 +37,7 @@ and pulling from, remote mirrors. To set up push mirroring for an existing project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a repository URL. @@ -89,12 +89,12 @@ To configure a mirror from GitLab to GitHub: 1. Enter a **Git repository URL** with this format, changing the variables as needed: ```plaintext - https://USERNAME@github.com/GROUP/PROJECT.git + https://github.com/GROUP/PROJECT.git ``` - - `USERNAME`: The username of the owner of the personal access token. - `GROUP`: The group on GitHub. - `PROJECT`: The project on GitHub. +1. For **Username**, enter the username of the owner of the personal access token. 1. For **Password**, enter your GitHub personal access token. 1. Select **Mirror repository**. @@ -164,19 +164,17 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. 1. Select **Settings > Repository**, and then expand **Mirroring repositories**. -1. Fill in the **Git repository URL** field using this format: +1. Fill in the **Git repository URL** field using this format, replacing + `<aws-region>` with your AWS region, and + `<your_codecommit_repo>` with the name of your repository in CodeCommit: ```plaintext - https://<your_aws_git_userid>@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + https://git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> ``` - Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** - from the IAM Git credentials created earlier. Replace `<your_codecommit_repo>` - with the name of your repository in CodeCommit. - -1. For **Mirror direction**, select **Push**. -1. For **Authentication method**, select **Password**. Fill in the **Password** box - with the special IAM Git clone user ID **password** created earlier in AWS. +1. For **Authentication method**, select **Username and Password**. +1. For **Username**, enter the AWS **special HTTPS Git user ID**. +1. For **Password**, enter the special IAM Git clone user ID password created earlier in AWS. 1. Leave the option **Only mirror protected branches** for CodeCommit. It pushes more frequently (from every five minutes to every minute). @@ -202,7 +200,8 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me [personal access token](../../../profile/personal_access_tokens.md) with `write_repository` scope. 1. On the source GitLab instance: 1. Enter the **Git repository URL** using this format: - `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + `https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + 1. Enter the **Username** `oauth2`. 1. Enter the **Password**. Use the GitLab personal access token created on the destination GitLab instance. 1. Select **Mirror repository**. diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md index 5817aab5fc7..a83231ceb63 100644 --- a/doc/user/project/repository/mirror/troubleshooting.md +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -67,7 +67,7 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. If no repository owner is specified, delete and add the URL again in this format, @@ -168,7 +168,7 @@ Prerequisites: To resolve the issue: 1. [Verify the host key](index.md#verify-a-host-key). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. To refresh the keys, either: diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 2756149b5bd..d61d09301a5 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -39,7 +39,7 @@ Prerequisite: To create global push rules: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Push Rules**. 1. Expand **Push rules**. @@ -52,7 +52,7 @@ The push rule of an individual project overrides the global push rule. To override global push rules for a specific project, or to update the rules for an existing project to match new global push rules: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Repository**. 1. Expand **Push rules**. 1. Set the rule you want. @@ -126,7 +126,7 @@ Some validation examples: Use these rules to prevent unintended consequences. -- **Reject unsigned commits**: Commit must be signed through [GPG](gpg_signed_commits/index.md). This rule +- **Reject unsigned commits**: Commit must be signed through [GPG](signed_commits/gpg.md). This rule can block some legitimate commits [created in the Web IDE](#reject-unsigned-commits-push-rule-disables-web-ide), and allow [unsigned commits created in the GitLab UI](#unsigned-commits-created-in-the-gitlab-ui). - **Do not allow users to remove Git tags with `git push`**: Users cannot use `git push` to remove Git tags. @@ -274,7 +274,7 @@ to use them as standard characters in a match condition. ## Related topics - [Git server hooks](../../../administration/server_hooks.md) (previously called server hooks), to create complex custom push rules -- [Signing commits with GPG](gpg_signed_commits/index.md) +- [Signing commits with GPG](signed_commits/gpg.md) - [Protected branches](../protected_branches.md) ## Troubleshooting diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 590323bfadd..bfe8964a876 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -26,7 +26,7 @@ you begin. The best way to back up a repository is to The size of a repository is determined by computing the accumulated size of all files in the repository. It is similar to executing `du --summarize --bytes` on your repository's -[hashed storage path](../../../administration/repository_storage_types.md). +[hashed storage path](../../../administration/repository_storage_paths.md). ## Purge files from repository history @@ -53,7 +53,7 @@ visible even after they have been removed from the repository. To purge files from a GitLab repository: -1. Install either [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) or +1. Install [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) and optionally [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. diff --git a/doc/user/project/repository/signed_commits/gpg.md b/doc/user/project/repository/signed_commits/gpg.md new file mode 100644 index 00000000000..88f6917d4b6 --- /dev/null +++ b/doc/user/project/repository/signed_commits/gpg.md @@ -0,0 +1,284 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Sign commits with GPG **(FREE ALL)** + +You can sign the commits you make in a GitLab repository with a +GPG ([GNU Privacy Guard](https://gnupg.org/)) key. + +NOTE: +GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and +implementations. + +For GitLab to consider a commit verified: + +- The committer must have a GPG public/private key pair. +- The committer's public key must be uploaded to their GitLab account. +- One of the email addresses in the GPG public key must match a **verified** email address + used by the committer in GitLab. To keep this address private, use the automatically generated + [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) + GitLab provides in your profile. +- The committer's email address must match the verified email address from the + GPG key. + +GitLab uses its own keyring to verify the GPG signature. It does not access any +public key server. + +GPG verified tags are not supported. + +For more details about GPG, refer to the [related topics list](#related-topics). + +## View a user's public GPG key + +To view a user's public GPG key, you can either: + +- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, + if the user has configured one, or a blank page for users without a configured GPG key. +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner + of the user's profile, select **View public GPG keys** (**{key}**). + +## Configure commit signing + +To sign commits, you must configure both your local machine and your GitLab account: + +1. [Create a GPG key](#create-a-gpg-key). +1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). +1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). +1. [Sign your Git commits](#sign-your-git-commits). + +### Create a GPG key + +If you don't already have a GPG key, create one: + +1. [Install GPG](https://www.gnupg.org/download/) for your operating system. + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in + the commands on this page. +1. To generate your key pair, run the command appropriate for your version of `gpg`: + + ```shell + # Use this command for the default version of GPG, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key + + # Use this command for versions of GPG later than 2.1.17: + gpg --full-gen-key + ``` + +1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select + the default option, `RSA and RSA`. +1. Select the key length, in bits. GitLab recommends 4096-bit keys. +1. Specify the validity period of your key. This value is subjective, and the + default value is no expiration. +1. To confirm your answers, enter `y`. +1. Enter your name. +1. Enter your email address. It must match a + [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) + in your GitLab account. +1. Optional. Enter a comment to display in parentheses after your name. +1. GPG displays the information you've entered so far. Edit the information or press + <kbd>O</kbd> (for `Okay`) to continue. +1. Enter a strong password, then enter it again to confirm it. +1. To list your private GPG key, run this command, replacing + `<EMAIL>` with the email address you used when you generated the key: + + ```shell + gpg --list-secret-keys --keyid-format LONG <EMAIL> + ``` + +1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after + the `/` character. In this example, the key ID is `30F2B65B9246B6CA`: + + ```plaintext + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` + +1. To show the associated public key, run this command, replacing `<ID>` with the + GPG key ID from the previous step: + + ```shell + gpg --armor --export <ID> + ``` + +1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and + `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step. + +### Add a GPG key to your account + +To add a GPG key to your user settings: + +1. Sign in to GitLab. +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **GPG Keys** (**{key}**). +1. Select **Add new key**. +1. In **Key**, paste your _public_ key. +1. To add the key to your account, select **Add key**. GitLab shows the key's + fingerprint, email address, and creation date: + +  + +After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. + +### Associate your GPG key with Git + +After you [create your GPG key](#create-a-gpg-key) and +[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git +to use this key: + +1. Run this command to list the private GPG key you just created, + replacing `<EMAIL>` with the email address for your key: + + ```shell + gpg --list-secret-keys --keyid-format LONG <EMAIL> + ``` + +1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is + `30F2B65B9246B6CA`: + + ```plaintext + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` + +1. Run this command to configure Git to sign your commits with your key, + replacing `<KEY ID>` with your GPG key ID: + + ```shell + git config --global user.signingkey <KEY ID> + ``` + +### Sign your Git commits + +After you [add your public key to your account](#add-a-gpg-key-to-your-account), +you can sign individual commits manually, or configure Git to default to signed commits: + +- Sign individual Git commits manually: + 1. Add `-S` flag to any commit you want to sign: + + ```shell + git commit -S -m "My commit message" + ``` + + 1. Enter the passphrase of your GPG key when asked. + 1. Push to GitLab and check that your commits [are verified](../signed_commits/index.md#verify-commits). +- Sign all Git commits by default by running this command: + + ```shell + git config --global commit.gpgsign true + ``` + +#### Set signing key conditionally + +If you maintain signing keys for separate purposes, such as work and personal +use, use an `IncludeIf` statement in your `.gitconfig` file to set which key +you sign commits with. + +Prerequisites: + +- Requires Git version 2.13 or later. + +1. In the same directory as your main `~/.gitconfig` file, create a second file, + such as `.gitconfig-gitlab`. +1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. +1. Append this information to the end of your main `~/.gitconfig` file: + + ```ini + # The contents of this file are included only for GitLab.com URLs + [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] + + # Edit this line to point to your alternate configuration file + path = ~/.gitconfig-gitlab + ``` + +1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to + use when you're committing to a GitLab repository. All settings from your + main `~/.gitconfig` file are retained unless you explicitly override them. + In this example, + + ```ini + # Alternate ~/.gitconfig-gitlab file + # These values are used for repositories matching the string 'gitlab.com', + # and override their corresponding values in ~/.gitconfig + + [user] + email = you@example.com + signingkey = <KEY ID> + + [commit] + gpgsign = true + ``` + +## Revoke a GPG key + +If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +To revoke a GPG key: + +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **GPG Keys** (**{key}**). +1. Select **Revoke** next to the GPG key you want to delete. + +## Remove a GPG key + +When you remove a GPG key from your GitLab account: + +- Previous commits signed with this key remain verified. +- Future commits (including any commits created but not yet pushed) that attempt + to use this key are unverified. + +To remove a GPG key from your account: + +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. Select **GPG Keys** (**{key}**). +1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. + +If you must unverify both future and past commits, +[revoke the associated GPG key](#revoke-a-gpg-key) instead. + +## Related topics + +- GPG resources: + - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) + - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) + - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) + - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + - [Review existing GPG keys in your instance](../../../../administration/credentials_inventory.md#review-existing-gpg-keys) + +## Troubleshooting + +### Secret key not available + +If you receive the errors `secret key not available` +or `gpg: signing failed: secret key not available`, try using `gpg2` instead of `gpg`: + +```shell +git config --global gpg.program gpg2 +``` + +If your GPG key is password protected and the password entry prompt does not appear, +add `export GPG_TTY=$(tty)` to your shell's `rc` file (commonly `~/.bashrc` or `~/.zshrc`) + +### GPG failed to sign the data + +If your GPG key is password protected and you receive the error: + +```shell +error: gpg failed to sign the data +fatal: failed to write commit object +``` + +If the password entry prompt does not appear, add `export GPG_TTY=$(tty)` to your shell's `rc` file +(commonly `~/.bashrc` or `~/.zshrc`) and restart your terminal. diff --git a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png b/doc/user/project/repository/signed_commits/img/profile_settings_gpg_keys_single_key.png Binary files differindex ae0a8696c6c..ae0a8696c6c 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png +++ b/doc/user/project/repository/signed_commits/img/profile_settings_gpg_keys_single_key.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png b/doc/user/project/repository/signed_commits/img/project_signed_and_unsigned_commits.png Binary files differindex e1d44f15f3f..e1d44f15f3f 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png +++ b/doc/user/project/repository/signed_commits/img/project_signed_and_unsigned_commits.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png b/doc/user/project/repository/signed_commits/img/project_signed_commit_unverified_signature.png Binary files differindex 763a677f94a..763a677f94a 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png +++ b/doc/user/project/repository/signed_commits/img/project_signed_commit_unverified_signature.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png b/doc/user/project/repository/signed_commits/img/project_signed_commit_verified_signature.png Binary files differindex 1b6fa3fc2e2..1b6fa3fc2e2 100644 --- a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png +++ b/doc/user/project/repository/signed_commits/img/project_signed_commit_verified_signature.png diff --git a/doc/user/project/repository/signed_commits/index.md b/doc/user/project/repository/signed_commits/index.md new file mode 100644 index 00000000000..e6632ecb81a --- /dev/null +++ b/doc/user/project/repository/signed_commits/index.md @@ -0,0 +1,64 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Signed commits **(FREE ALL)** + +When you add a cryptographic signature to your commit, you provide extra assurance that a commit +originated from you, rather than an impersonator. If GitLab can verify a commit +author's identity with a public GPG key, the commit is marked **Verified** in the +GitLab UI. You can then configure [push rules](../push_rules.md) +for your project to reject individual commits not signed with GPG, or reject all +commits from unverified users. + +Sign commits with your: + +- [SSH key](ssh.md). +- [GPG key](gpg.md). +- [Personal x.509 certificate](x509.md). + +## Verify commits + +You can review commits for a merge request, or for an entire project, to confirm +they are signed: + +1. To review commits for a project: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Commits**. +1. To review commits for a merge request: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. Select **Commits**. +1. Identify the commit you want to review. Signed commits show either a **Verified** + or **Unverified** badge, depending on the verification status of the signature. + Unsigned commits do not display a badge: + +  + +1. To display the signature details for a commit, select **Verified** to see + the fingerprint or key ID: + +  + +  + +You can also [use the Commits API](../../../../api/commits.md#get-gpg-signature-of-a-commit) +to check a commit's signature. + +## Troubleshooting + +### Fix verification problems with signed commits + +The verification process for commits signed with GPG keys or X.509 certificates +can fail for multiple reasons: + +| Value | Description | Possible Fixes | +|-----------------------------|-------------|----------------| +| `UNVERIFIED` | The commit signature is not valid. | Sign the commit with a valid signature. | +| `SAME_USER_DIFFERENT_EMAIL` | The GPG key used to sign the commit does not contain the committer email, but does contain a different valid email for the committer. | Amend the commit to use an email address that matches the GPG key, or update the GPG key [to include the email address](https://security.stackexchange.com/a/261468). | +| `OTHER_USER` | The signature and GPG key are valid, but the key belongs to a different user than the committer. | Amend the commit to use the correct email address, or amend the commit to use a GPG key associated with your user. | +| `UNVERIFIED_KEY` | The key associated with the GPG signature has no verified email address associated with the committer. | Add and verify the email to your GitLab profile, [update the GPG key to include the email address](https://security.stackexchange.com/a/261468), or amend the commit to use a different committer email address. | +| `UNKNOWN_KEY` | The GPG key associated with the GPG signature for this commit is unknown to GitLab. | [Add the GPG key](gpg.md#add-a-gpg-key-to-your-account) to your GitLab profile. | +| `MULTIPLE_SIGNATURES` | Multiple GPG or X.509 signatures have been found for the commit. | Amend the commit to use only one GPG or X.509 signature. | diff --git a/doc/user/project/repository/signed_commits/ssh.md b/doc/user/project/repository/signed_commits/ssh.md new file mode 100644 index 00000000000..3572e56da84 --- /dev/null +++ b/doc/user/project/repository/signed_commits/ssh.md @@ -0,0 +1,167 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Sign commits with SSH keys **(FREE ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. + +When you sign commits with SSH keys, GitLab uses the SSH public keys associated +with your GitLab account to cryptographically verify the commit signature. +If successful, GitLab displays a **Verified** label on the commit. + +You may use the same SSH keys for `git+ssh` authentication to GitLab +and signing commit signatures as long as their usage type is **Authentication & Signing**. +It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). + +For more information about managing the SSH keys associated with your GitLab account, see +[Use SSH keys to communicate with GitLab](../../../ssh.md). + +## Configure Git to sign commits with your SSH key + +After you [create an SSH key](../../../ssh.md#generate-an-ssh-key-pair) and +[add it to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) +or [generate it using a password manager](../../../ssh.md#generate-an-ssh-key-pair-with-a-password-manager), +configure Git to begin using the key. + +Prerequisites: + +- Git 2.34.0 or newer. +- OpenSSH 8.0 or newer. + + NOTE: + OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8. + +- A SSH key with the usage type of either **Authentication & Signing** or **Signing**. + The SSH key must be one of these types: + - [ED25519](../../../ssh.md#ed25519-ssh-keys) (recommended) + - [RSA](../../../ssh.md#rsa-ssh-keys) + +To configure Git to use your key: + +1. Configure Git to use SSH for commit signing: + + ```shell + git config --global gpg.format ssh + ``` + +1. Specify which SSH key should be used as the signing key, changing the filename + (here, `~/.ssh/examplekey`) to the location of your key. The filename may + differ, depending on how you generated your key: + + ```shell + git config --global user.signingkey ~/.ssh/examplekey + ``` + +## Sign commits with your SSH key + +Prerequisites: + +- You've [created an SSH key](../../../ssh.md#generate-an-ssh-key-pair). +- You've [added the key](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) to your GitLab account. +- You've [configured Git to sign commits](#configure-git-to-sign-commits-with-your-ssh-key) with your SSH key. + +To sign a commit: + +1. Use the `-S` flag when signing your commits: + + ```shell + git commit -S -m "My commit msg" + ``` + +1. Optional. If you don't want to type the `-S` flag every time you commit, tell + Git to sign your commits automatically: + + ```shell + git config --global commit.gpgsign true + ``` + +1. If your SSH key is protected, Git prompts you to enter your passphrase. +1. Push to GitLab. +1. Check that your commits [are verified](#verify-commits). + Signature verification uses the `allowed_signers` file to associate emails and SSH keys. + For help configuring this file, read [Verify commits locally](#verify-commits-locally). + +## Verify commits + +You can verify all types of signed commits +[in the GitLab UI](../signed_commits/index.md#verify-commits). Commits signed +with an SSH key can also be verified locally. + +### Verify commits locally + +To verify commits locally, create an +[allowed signers file](https://man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) +for Git to associate SSH public keys with users: + +1. Create an allowed signers file: + + ```shell + touch allowed_signers + ``` + +1. Configure the `allowed_signers` file in Git: + + ```shell + git config gpg.ssh.allowedSignersFile "$(pwd)/allowed_signers" + ``` + +1. Add your entry to the allowed signers file. Use this command to add your + email address and public SSH key to the `allowed_signers` file. Replace `<MY_KEY>` + with the name of your key, and `~/.ssh/allowed_signers` + with the location of your project's `allowed_signers` file: + + ```shell + # Modify this line to meet your needs. + # Declaring the `git` namespace helps prevent cross-protocol attacks. + echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/<MY_KEY>.pub)" >> ~/.ssh/allowed_signers + ``` + + The resulting entry in the `allowed_signers` file contains your email address, key type, + and key contents, like this: + + ```plaintext + example@gitlab.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv + ``` + +1. Repeat the previous step for each user who you want to verify signatures for. + Consider checking this file in to your Git repository if you want to locally + verify signatures for many different contributors. + +1. Use `git log --show-signature` to view the signature status for the commits: + + ```shell + $ git log --show-signature + + commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD) + Good "git" signature for johndoe@example.com with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc + Author: John Doe <johndoe@example.com> + Date: Tue Nov 29 06:54:15 2022 -0600 + + SSH signed commit + ``` + +## Revoke an SSH key for signing commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. + +If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +To revoke an SSH key: + +1. On the left sidebar, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select (**{key}**) **SSH Keys**. +1. Select **Revoke** next to the SSH key you want to delete. + +## Related topics + +- [Sign commits and tags with X.509 certificates](../signed_commits/x509.md) +- [Sign commits with GPG](gpg.md) +- [Commits API](../../../../api/commits.md) diff --git a/doc/user/project/repository/signed_commits/x509.md b/doc/user/project/repository/signed_commits/x509.md new file mode 100644 index 00000000000..17767cbd8f4 --- /dev/null +++ b/doc/user/project/repository/signed_commits/x509.md @@ -0,0 +1,362 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Sign commits and tags with X.509 certificates **(FREE ALL)** + +[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key +certificates issued by a public or private Public Key Infrastructure (PKI). +Personal X.509 certificates are used for authentication or signing purposes +such as S/MIME (Secure/Multipurpose Internet Mail Extensions). +However, Git also supports signing of commits and tags with X.509 certificates in a +similar way as with [GPG (GnuPG, or GNU Privacy Guard)](gpg.md). +The main difference is the way GitLab determines whether or not the developer's signature is trusted: + +- For X.509, a root certificate authority is added to the GitLab trust store. + (A trust store is a repository of trusted security certificates.) Combined with + any required intermediate certificates in the signature, the developer's certificate + can be chained back to a trusted root certificate. +- For GPG, developers [add their GPG key](gpg.md#add-a-gpg-key-to-your-account) + to their account. + +GitLab uses its own certificate store and therefore defines the +[trust chain](https://www.ssl.com/faqs/what-is-a-certificate-authority/). +For a commit or tag to be *verified* by GitLab: + +- The signing certificate email must match a verified email address in GitLab. +- The GitLab instance must be able to establish a full trust chain + from the certificate in the signature to a trusted certificate in the GitLab certificate store. + This chain may include intermediate certificates supplied in the signature. You may + need to add certificates, such as Certificate Authority root certificates, + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). +- The signing time must be in the time range of the + [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), + which is usually up to three years. +- The signing time is equal to, or later than, the commit time. + +If a commit's status has already been determined and stored in the database, +use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). +Refer to the [Troubleshooting section](#troubleshooting). +GitLab checks certificate revocation lists on a daily basis with a background worker. + +## Limitations + +- Certificates without `authorityKeyIdentifier`, + `subjectKeyIdentifier`, and `crlDistributionPoints` display as **Unverified**. We + recommend using certificates from a PKI that are in line with + [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280). +- If you have more than one email in the Subject Alternative Name list in + your signing certificate, + [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). +- The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the + signing certificate + [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). + If your SKI is shorter, commits don't show as verified in GitLab, and + short subject key identifiers may also + [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), + such as 'An error occurred while loading commit signatures' and + `HTTP 422 Unprocessable Entity` errors. + +## Configure for signed commits + +To sign your commits, tags, or both, you must: + +1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). +1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). +1. [Sign and verify commits](#sign-and-verify-commits). +1. [Sign and verify tags](#sign-and-verify-tags). + +### Obtain an X.509 key pair + +If your organization has Public Key Infrastructure (PKI), that PKI provides +an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either +create your own self-signed pair, or purchase a pair. + +### Associate your X.509 certificate with Git + +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can +check your Git version with the command `git --version`. + +If you have the correct version, you can proceed to configure Git. + +### Linux + +Configure Git to use your key for signing: + +```shell +signingkey=$( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) +git config --global user.signingkey $signingkey +git config --global gpg.format x509 +``` + +#### Windows and macOS + +To configure Windows or macOS: + +1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: + - Downloading the installer. + - Running `brew install smimesign` on macOS. +1. Get the ID of your certificate by running `smimesign --list-keys`. +1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. +1. Configure X.509 with this command: + + ```shell + git config --global gpg.x509.program smimesign + git config --global gpg.format x509 + ``` + +### Sign and verify commits + +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can sign your commits: + +1. When you create a Git commit, add the `-S` flag: + + ```shell + git commit -S -m "feat: x509 signed commits" + ``` + +1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: + + ```shell + git log --show-signature + ``` + +1. *If you don't want to type the `-S` flag every time you commit,* run this command + for Git to sign your commits every time: + + ```shell + git config --global commit.gpgsign true + ``` + +### Sign and verify tags + +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can start signing your tags: + +1. When you create a Git tag, add the `-s` flag: + + ```shell + git tag -s v1.1.1 -m "My signed tag" + ``` + +1. Push to GitLab and verify your tags are signed with this command: + + ```shell + git tag --verify v1.1.1 + ``` + +1. *If you don't want to type the `-s` flag every time you tag,* run this command + for Git to sign your tags each time: + + ```shell + git config --global tag.gpgsign true + ``` + +## Related topics + +- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) + +## Troubleshooting + +For committers without administrator access, review the list of +[verification problems with signed commits](../signed_commits/index.md#fix-verification-problems-with-signed-commits) +for possible fixes. The other troubleshooting suggestions on this page require +administrator access. + +### Re-verify commits + +GitLab stores the status of any checked commits in the database. You can use a +Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). + +After you make any changes, run this command: + +```shell +sudo gitlab-rake gitlab:x509:update_signatures +``` + +### Main verification checks + +The code performs +[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), +which all must return `verified`: + +- `x509_certificate.nil?` should be false. +- `x509_certificate.revoked?` should be false. +- `verified_signature` should be true. +- `user.nil?` should be false. +- `user.verified_emails.include?(@email)` should be true. +- `certificate_email == @email` should be true. + +To investigate why a commit shows as `Unverified`: + +1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```shell + sudo gitlab-rails console + ``` + +1. Identify the project (either by path or ID) and full commit SHA that you're investigating. + Use this information to create `signature` to run other checks against: + + ```ruby + project = Project.find_by_full_path('group/subgroup/project') + project = Project.find_by_id('121') + commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') + signedcommit=Gitlab::X509::Commit.new(commit) + signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) + ``` + + If you make changes to address issues identified running through the checks, restart the + Rails console and run though the checks again from the start. + +1. Check the certificate on the commit: + + ```ruby + signature.x509_certificate.nil? + signature.x509_certificate.revoked? + ``` + + Both checks should return `false`: + + ```ruby + > signature.x509_certificate.nil? + => false + > signature.x509_certificate.revoked? + => false + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes + these checks to fail with `Validation failed: Subject key identifier is invalid`. + +1. Run a cryptographic check on the signature. The code must return `true`: + + ```ruby + signature.verified_signature + ``` + + If it returns `false` then [investigate this check further](#cryptographic-verification-checks). + +1. Confirm the email addresses match on the commit and the signature: + + - The Rails console displays the email addresses being compared. + - The final command must return `true`: + + ```ruby + sigemail=signature.__send__:certificate_email + commitemail=commit.committer_email + sigemail == commitemail + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: + only the first email in the `Subject Alternative Name` list is compared. To + display the `Subject Alternative Name` list, run: + + ```ruby + signature.__send__ :get_certificate_extension,'subjectAltName' + ``` + + If the developer's email address is not the first one in the list, this check + fails, and the commit is marked `unverified`. + +1. The email address on the commit must be associated with an account in GitLab. + This check should return `false`: + + ```ruby + signature.user.nil? + ``` + +1. Check the email address is associated with a user in GitLab. This check should + return a user, such as `#<User id:1234 @user_handle>`: + + ```ruby + User.find_by_any_email(commit.committer_email) + ``` + + If it returns `nil`, the email address is not associated with a user, and the check fails. + +1. Confirm the developer's email address is verified. This check must return true: + + ```ruby + signature.user.verified_emails.include?(commit.committer_email) + ``` + + If the previous check returned `nil`, this command displays an error: + + ```plaintext + NoMethodError (undefined method `verified_emails' for nil:NilClass) + ``` + +1. The verification status is stored in the database. To display the database record: + + ```ruby + pp CommitSignatures::X509CommitSignature.by_commit_sha(commit.sha);nil + ``` + + If all the previous checks returned the correct values: + + - `verification_status: "unverified"` indicates the database record needs + updating. [Use the Rake task](#re-verify-commits). + + - `[]` indicates the database doesn't have a record yet. Locate the commit + in GitLab to check the signature and store the result. + +#### Cryptographic verification checks + +If GitLab determines that `verified_signature` is `false`, investigate the reason +in the Rails console. These checks require `signature` to exist. Refer to the `signature` +step of the previous [main verification checks](#main-verification-checks). + +1. Check the signature, without checking the issuer, returns `true`: + + ```ruby + signature.__send__ :valid_signature? + ``` + +1. Check the signing time and date. This check must return `true`: + + ```ruby + signature.__send__ :valid_signing_time? + ``` + + - The code allows for code signing certificates to expire. + - A commit must be signed during the validity period of the certificate, + and at or after the commit's datestamp. Display the commit time and + certificate details including `not_before`, `not_after` with: + + ```ruby + commit.created_at + pp signature.__send__ :cert; nil + ``` + +1. Check the signature, including that TLS trust can be established. This check must return `true`: + + ```ruby + signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) + ``` + + 1. If this fails, add the missing certificates required to establish trust + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). + + 1. After adding more certificates, (if these troubleshooting steps then pass) + run the Rake task to [re-verify commits](#re-verify-commits). + + 1. Display the certificates, including in the signature: + + ```ruby + pp signature.__send__(:p7).certificates ; nil + ``` + +Ensure any additional intermediate certificates and the root certificate are added +to the certificate store. For consistency with how certificate chains are built on +web servers: + +- Git clients that are signing commits should include the certificate + and all intermediate certificates in the signature. +- The GitLab certificate store should only contain the root. + +If you remove a root certificate from the GitLab +trust store, such as when it expires, commit signatures which chain back to that +root display as `unverified`. diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index d8d798ac651..89e3d811dba 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -1,181 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../signed_commits/ssh.md' +remove_date: '2023-12-01' --- -# Sign commits with SSH keys **(FREE ALL)** +This document was moved to [another location](../signed_commits/ssh.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. - -Use SSH keys to sign Git commits in the same manner as -[GPG signed commits](../gpg_signed_commits/index.md). When you sign commits -with SSH keys, GitLab uses the SSH public keys associated with your -GitLab account to cryptographically verify the commit signature. -If successful, GitLab displays a **Verified** label on the commit. - -You may use the same SSH keys for `git+ssh` authentication to GitLab -and signing commit signatures as long as their usage type is **Authentication & Signing**. -It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). - -For more information about managing the SSH keys associated with your GitLab account, see -[Use SSH keys to communicate with GitLab](../../../ssh.md). - -## Configure Git to sign commits with your SSH key - -After you [create an SSH key](../../../ssh.md#generate-an-ssh-key-pair) and -[add it to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) -or [generate it using a password manager](../../../ssh.md#generate-an-ssh-key-pair-with-a-password-manager), -configure Git to begin using the key. - -Prerequisites: - -- Git 2.34.0 or newer. -- OpenSSH 8.0 or newer. - - NOTE: - OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8. - -- A SSH key with the usage type of either **Authentication & Signing** or **Signing**. - The SSH key must be one of these types: - - [ED25519](../../../ssh.md#ed25519-ssh-keys) (recommended) - - [RSA](../../../ssh.md#rsa-ssh-keys) - -To configure Git to use your key: - -1. Configure Git to use SSH for commit signing: - - ```shell - git config --global gpg.format ssh - ``` - -1. Specify which SSH key should be used as the signing key, changing the filename - (here, `~/.ssh/examplekey`) to the location of your key. The filename may - differ, depending on how you generated your key: - - ```shell - git config --global user.signingkey ~/.ssh/examplekey - ``` - -## Sign commits with your SSH key - -Prerequisites: - -- You've [created an SSH key](../../../ssh.md#generate-an-ssh-key-pair). -- You've [added the key](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) to your GitLab account. -- You've [configured Git to sign commits](#configure-git-to-sign-commits-with-your-ssh-key) with your SSH key. - -To sign a commit: - -1. Use the `-S` flag when signing your commits: - - ```shell - git commit -S -m "My commit msg" - ``` - -1. Optional. If you don't want to type the `-S` flag every time you commit, tell - Git to sign your commits automatically: - - ```shell - git config --global commit.gpgsign true - ``` - -1. If your SSH key is protected, Git prompts you to enter your passphrase. -1. Push to GitLab. -1. Check that your commits [are verified](#verify-commits). - Signature verification uses the `allowed_signers` file to associate emails and SSH keys. - For help configuring this file, read [Verify commits locally](#verify-commits-locally). - -## Verify commits - -You can review commits for a merge request, or for an entire project, to confirm -they are signed: - -1. To review commits for a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Commits**. -1. To review commits for a merge request: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. On the left sidebar, select **Merge requests**, then select your merge request. - 1. Select **Commits**. -1. Identify the commit you want to review. Signed commits show either a **Verified** - or **Unverified** badge, depending on the verification status of the signature. - Unsigned commits do not display a badge. -1. To display the signature details for a commit, select **Verified**. GitLab shows - the SSH key's fingerprint. - -## Verify commits locally - -To verify commits locally, create an -[allowed signers file](https://man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) -for Git to associate SSH public keys with users: - -1. Create an allowed signers file: - - ```shell - touch allowed_signers - ``` - -1. Configure the `allowed_signers` file in Git: - - ```shell - git config gpg.ssh.allowedSignersFile "$(pwd)/allowed_signers" - ``` - -1. Add your entry to the allowed signers file. Use this command to add your - email address and public SSH key to the `allowed_signers` file. Replace `<MY_KEY>` - with the name of your key, and `~/.ssh/allowed_signers` - with the location of your project's `allowed_signers` file: - - ```shell - # Modify this line to meet your needs. - # Declaring the `git` namespace helps prevent cross-protocol attacks. - echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/<MY_KEY>.pub)" >> ~/.ssh/allowed_signers - ``` - - The resulting entry in the `allowed_signers` file contains your email address, key type, - and key contents, like this: - - ```plaintext - example@gitlab.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv - ``` - -1. Repeat the previous step for each user who you want to verify signatures for. - Consider checking this file in to your Git repository if you want to locally - verify signatures for many different contributors. - -1. Use `git log --show-signature` to view the signature status for the commits: - - ```shell - $ git log --show-signature - - commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD) - Good "git" signature for johndoe@example.com with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc - Author: John Doe <johndoe@example.com> - Date: Tue Nov 29 06:54:15 2022 -0600 - - SSH signed commit - ``` - -## Revoke an SSH key for signing commits - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. - -If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: - -- Past commits signed by this key are marked as unverified. -- Future commits signed by this key are marked as unverified. - -To revoke an SSH key: - -1. On the left sidebar, select your avatar. -1. Select **Edit profile**. -1. On the left sidebar, select (**{key}**) **SSH Keys**. -1. Select **Revoke** next to the SSH key you want to delete. - -## Related topics - -- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) -- [Sign commits with GPG](../gpg_signed_commits/index.md) -- [Commits API](../../../../api/commits.md) +<!-- This redirect file can be deleted after <2023-12-01>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index 5a01d6f2085..765f5539244 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -44,14 +44,14 @@ In the GitLab UI, each tag displays: To view all existing tags for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Tags**. ## View tagged commits in the commits list > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Commits**. 1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. This example shows a commit tagged `v1.26.0`: @@ -88,7 +88,7 @@ To create either a lightweight or annotated tag from the command line, and push To create a tag from the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Tags**. 1. Select **New tag**. 1. Provide a **Tag name**. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 121a7b41f54..3acc62186a3 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -25,7 +25,7 @@ for any change you commit through the Web Editor. To create a text file in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. @@ -35,7 +35,7 @@ To create a text file in the Web Editor: ### Create a file from a template -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Repository**. 1. Next to the project name, select the plus icon (**{plus}**) to display a dropdown list, then select **New file** from the list. @@ -56,7 +56,7 @@ To create a text file in the Web Editor: To edit a text file in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Go to your file. 1. In the upper right, select **Edit > Edit single file**. @@ -105,7 +105,7 @@ To upload a binary file in the Web Editor: <!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> <!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. 1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -115,7 +115,7 @@ To upload a binary file in the Web Editor: To create a directory in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New directory**. 1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -125,7 +125,7 @@ To create a directory in the Web Editor: To create a [branch](branches/index.md) in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New branch**. 1. Complete the fields. @@ -136,7 +136,7 @@ To create a [branch](branches/index.md) in the Web Editor: You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New tag**. 1. Complete the fields. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 20860718b43..ae418581820 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,366 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../signed_commits/x509.md' +remove_date: '2023-12-01' --- -# Sign commits and tags with X.509 certificates **(FREE ALL)** +This document was moved to [another location](../signed_commits/x509.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. - -[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key -certificates issued by a public or private Public Key Infrastructure (PKI). -Personal X.509 certificates are used for authentication or signing purposes -such as S/MIME (Secure/Multipurpose Internet Mail Extensions). -However, Git also supports signing of commits and tags with X.509 certificates in a -similar way as with [GPG (GnuPG, or GNU Privacy Guard)](../gpg_signed_commits/index.md). -The main difference is the way GitLab determines whether or not the developer's signature is trusted: - -- For X.509, a root certificate authority is added to the GitLab trust store. - (A trust store is a repository of trusted security certificates.) Combined with - any required intermediate certificates in the signature, the developer's certificate - can be chained back to a trusted root certificate. -- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#add-a-gpg-key-to-your-account) - to their account. - -GitLab uses its own certificate store and therefore defines the -[trust chain](https://www.ssl.com/faqs/what-is-a-certificate-authority/). -For a commit or tag to be *verified* by GitLab: - -- The signing certificate email must match a verified email address in GitLab. -- The GitLab instance must be able to establish a full trust chain - from the certificate in the signature to a trusted certificate in the GitLab certificate store. - This chain may include intermediate certificates supplied in the signature. You may - need to add certificates, such as Certificate Authority root certificates, - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). -- The signing time must be in the time range of the - [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), - which is usually up to three years. -- The signing time is equal to, or later than, the commit time. - -If a commit's status has already been determined and stored in the database, -use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). -Refer to the [Troubleshooting section](#troubleshooting). -GitLab checks certificate revocation lists on a daily basis with a background worker. - -## Limitations - -- Self-signed certificates without `authorityKeyIdentifier`, - `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We - recommend using certificates from a PKI that are in line with - [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280). -- If you have more than one email in the Subject Alternative Name list in - your signing certificate, - [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). -- The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the - signing certificate - [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). - If your SKI is shorter, commits don't show as verified in GitLab, and - short subject key identifiers may also - [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), - such as 'An error occurred while loading commit signatures' and - `HTTP 422 Unprocessable Entity` errors. - -## Configure for signed commits - -To sign your commits, tags, or both, you must: - -1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). -1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). -1. [Sign and verify commits](#sign-and-verify-commits). -1. [Sign and verify tags](#sign-and-verify-tags). - -### Obtain an X.509 key pair - -If your organization has Public Key Infrastructure (PKI), that PKI provides -an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either -create your own self-signed pair, or purchase a pair. - -### Associate your X.509 certificate with Git - -To take advantage of X.509 signing, you need Git 2.19.0 or later. You can -check your Git version with the command `git --version`. - -If you have the correct version, you can proceed to configure Git. - -### Linux - -Configure Git to use your key for signing: - -```shell -signingkey=$( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) -git config --global user.signingkey $signingkey -git config --global gpg.format x509 -``` - -#### Windows and macOS - -To configure Windows or macOS: - -1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: - - Downloading the installer. - - Running `brew install smimesign` on macOS. -1. Get the ID of your certificate by running `smimesign --list-keys`. -1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. -1. Configure X.509 with this command: - - ```shell - git config --global gpg.x509.program smimesign - git config --global gpg.format x509 - ``` - -### Sign and verify commits - -After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you -can sign your commits: - -1. When you create a Git commit, add the `-S` flag: - - ```shell - git commit -S -m "feat: x509 signed commits" - ``` - -1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: - - ```shell - git log --show-signature - ``` - -1. *If you don't want to type the `-S` flag every time you commit,* run this command - for Git to sign your commits every time: - - ```shell - git config --global commit.gpgsign true - ``` - -### Sign and verify tags - -After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you -can start signing your tags: - -1. When you create a Git tag, add the `-s` flag: - - ```shell - git tag -s v1.1.1 -m "My signed tag" - ``` - -1. Push to GitLab and verify your tags are signed with this command: - - ```shell - git tag --verify v1.1.1 - ``` - -1. *If you don't want to type the `-s` flag every time you tag,* run this command - for Git to sign your tags each time: - - ```shell - git config --global tag.gpgsign true - ``` - -## Related topics - -- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) -- [Sign commits with GPG](../gpg_signed_commits/index.md) -- [Sign commits with SSH keys](../ssh_signed_commits/index.md) - -## Troubleshooting - -For committers without administrator access, review the list of -[verification problems with signed commits](../gpg_signed_commits/index.md#fix-verification-problems-with-signed-commits) -for possible fixes. The other troubleshooting suggestions on this page require -administrator access. - -### Re-verify commits - -GitLab stores the status of any checked commits in the database. You can use a -Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). - -After you make any changes, run this command: - -```shell -sudo gitlab-rake gitlab:x509:update_signatures -``` - -### Main verification checks - -The code performs -[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), -which all must return `verified`: - -- `x509_certificate.nil?` should be false. -- `x509_certificate.revoked?` should be false. -- `verified_signature` should be true. -- `user.nil?` should be false. -- `user.verified_emails.include?(@email)` should be true. -- `certificate_email == @email` should be true. - -To investigate why a commit shows as `Unverified`: - -1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```shell - sudo gitlab-rails console - ``` - -1. Identify the project (either by path or ID) and full commit SHA that you're investigating. - Use this information to create `signature` to run other checks against: - - ```ruby - project = Project.find_by_full_path('group/subgroup/project') - project = Project.find_by_id('121') - commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') - signedcommit=Gitlab::X509::Commit.new(commit) - signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) - ``` - - If you make changes to address issues identified running through the checks, restart the - Rails console and run though the checks again from the start. - -1. Check the certificate on the commit: - - ```ruby - signature.x509_certificate.nil? - signature.x509_certificate.revoked? - ``` - - Both checks should return `false`: - - ```ruby - > signature.x509_certificate.nil? - => false - > signature.x509_certificate.revoked? - => false - ``` - - A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes - these checks to fail with `Validation failed: Subject key identifier is invalid`. - -1. Run a cryptographic check on the signature. The code must return `true`: - - ```ruby - signature.verified_signature - ``` - - If it returns `false` then [investigate this check further](#cryptographic-verification-checks). - -1. Confirm the email addresses match on the commit and the signature: - - - The Rails console displays the email addresses being compared. - - The final command must return `true`: - - ```ruby - sigemail=signature.__send__:certificate_email - commitemail=commit.committer_email - sigemail == commitemail - ``` - - A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: - only the first email in the `Subject Alternative Name` list is compared. To - display the `Subject Alternative Name` list, run: - - ```ruby - signature.__send__ :get_certificate_extension,'subjectAltName' - ``` - - If the developer's email address is not the first one in the list, this check - fails, and the commit is marked `unverified`. - -1. The email address on the commit must be associated with an account in GitLab. - This check should return `false`: - - ```ruby - signature.user.nil? - ``` - -1. Check the email address is associated with a user in GitLab. This check should - return a user, such as `#<User id:1234 @user_handle>`: - - ```ruby - User.find_by_any_email(commit.committer_email) - ``` - - If it returns `nil`, the email address is not associated with a user, and the check fails. - -1. Confirm the developer's email address is verified. This check must return true: - - ```ruby - signature.user.verified_emails.include?(commit.committer_email) - ``` - - If the previous check returned `nil`, this command displays an error: - - ```plaintext - NoMethodError (undefined method `verified_emails' for nil:NilClass) - ``` - -1. The verification status is stored in the database. To display the database record: - - ```ruby - pp CommitSignatures::X509CommitSignature.by_commit_sha(commit.sha);nil - ``` - - If all the previous checks returned the correct values: - - - `verification_status: "unverified"` indicates the database record needs - updating. [Use the Rake task](#re-verify-commits). - - - `[]` indicates the database doesn't have a record yet. Locate the commit - in GitLab to check the signature and store the result. - -#### Cryptographic verification checks - -If GitLab determines that `verified_signature` is `false`, investigate the reason -in the Rails console. These checks require `signature` to exist. Refer to the `signature` -step of the previous [main verification checks](#main-verification-checks). - -1. Check the signature, without checking the issuer, returns `true`: - - ```ruby - signature.__send__ :valid_signature? - ``` - -1. Check the signing time and date. This check must return `true`: - - ```ruby - signature.__send__ :valid_signing_time? - ``` - - - The code allows for code signing certificates to expire. - - A commit must be signed during the validity period of the certificate, - and at or after the commit's datestamp. Display the commit time and - certificate details including `not_before`, `not_after` with: - - ```ruby - commit.created_at - pp signature.__send__ :cert; nil - ``` - -1. Check the signature, including that TLS trust can be established. This check must return `true`: - - ```ruby - signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) - ``` - - 1. If this fails, add the missing certificates required to establish trust - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). - - 1. After adding more certificates, (if these troubleshooting steps then pass) - run the Rake task to [re-verify commits](#re-verify-commits). - - 1. Display the certificates, including in the signature: - - ```ruby - pp signature.__send__(:p7).certificates ; nil - ``` - -Ensure any additional intermediate certificates and the root certificate are added -to the certificate store. For consistency with how certificate chains are built on -web servers: - -- Git clients that are signing commits should include the certificate - and all intermediate certificates in the signature. -- The GitLab certificate store should only contain the root. - -If you remove a root certificate from the GitLab -trust store, such as when it expires, commit signatures which chain back to that -root display as `unverified`. +<!-- This redirect file can be deleted after <2023-12-01>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 1f79982bb1f..d99729e3c1b 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -137,7 +137,7 @@ You can also sort the requirements list by: ## Allow requirements to be satisfied from a CI job > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in GitLab 13.2. +> - Ability to specify individual requirements and their statuses [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) in GitLab 13.2. GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing diff --git a/doc/user/project/service_desk/configure.md b/doc/user/project/service_desk/configure.md new file mode 100644 index 00000000000..f8f4ab44e5a --- /dev/null +++ b/doc/user/project/service_desk/configure.md @@ -0,0 +1,873 @@ +--- +stage: Monitor +group: Respond +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Configure Service Desk **(FREE ALL)** + +By default, Service Desk is active in new projects. +If it's not active, you can do it in the project's settings. + +Prerequisites: + +- You must have at least the Maintainer role for the project. +- On GitLab self-managed, you must [set up incoming email](../../../administration/incoming_email.md#set-it-up) + for the GitLab instance. You should use + [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), + but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). + To do this, you must have administrator access. +- You must have enabled [issue](../settings/index.md#configure-project-features-and-permissions) + tracker for the project. + +To enable Service Desk in your project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Activate Service Desk** toggle. +1. Optional. Complete the fields. + - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. + - If the list below **Template to append to all Service Desk issues** is empty, create a + [description template](../description_templates.md) in your repository. +1. Select **Save changes**. + +Service Desk is now enabled for this project. +If anyone sends an email to the address available below **Email address to use for Service Desk**, +GitLab creates a confidential issue with the email's content. + +## Improve your project's security + +To improve your Service Desk project's security, you should: + +- Put the Service Desk email address behind an alias on your email system so you can change it later. +- [Enable Akismet](../../../integration/akismet.md) on your GitLab instance to add spam checking to this service. + Unblocked email spam can result in many spam issues being created. + +## Customize emails sent to the requester + +> - Moved from GitLab Premium to GitLab Free in 13.2. +> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. +> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. + +An email is sent to the requester when: + +- A requester submits a new ticket by emailing Service Desk. +- A new public comment is added on a Service Desk ticket. + - Editing a comment does not trigger a new email to be sent. + +You can customize the body of these email messages with Service Desk email templates. The templates +can include [GitLab Flavored Markdown](../../markdown.md) and [some HTML tags](../../markdown.md#inline-html). +For example, you can format the emails to include a header and footer in accordance with your +organization's brand guidelines. You can also include the following placeholders to display dynamic +content specific to the Service Desk ticket or your GitLab instance. + +| Placeholder | `thank_you.md` | `new_note.md` | Description +| ---------------------- | ---------------------- | ---------------------- | ----------- +| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. +| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. +| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). +| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. +| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. +| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. + +### Thank you email + +When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. +Without additional configuration, GitLab sends the default thank you email. + +To create a custom thank you email template: + +1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), + [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the reply + to Service Desk requesters. + +### New note email + +When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. +Without additional configuration, GitLab sends the content of the comment. + +To keep your emails on brand, you can create a custom new note email template. To do so: + +1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), + [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the new note + email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can + read the contents of the comment. + +### Instance-level email header, footer, and additional text **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. + +Instance administrators can add a header, footer or additional text to the GitLab instance and apply +them to all emails sent from GitLab. If you're using a custom `thank_you.md` or `new_note.md`, to include +this content, add `%{SYSTEM_HEADER}`, `%{SYSTEM_FOOTER}`, or `%{ADDITIONAL_TEXT}` to your templates. + +For more information, see [System header and footer messages](../../../administration/appearance.md#system-header-and-footer-messages) and [custom additional text](../../../administration/settings/email.md#custom-additional-text). + +## Use a custom template for Service Desk tickets + +You can select one [description template](../description_templates.md#create-an-issue-template) +**per project** to be appended to every new Service Desk ticket's description. + +You can set description templates at various levels: + +- The entire [instance](../description_templates.md#set-instance-level-description-templates). +- A specific [group or subgroup](../description_templates.md#set-group-level-description-templates). +- A specific [project](../description_templates.md#set-a-default-template-for-merge-requests-and-issues). + +The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. + +Prerequisite: + +- You must have [created a description template](../description_templates.md#create-an-issue-template). + +To use a custom description template with Service Desk: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. + +## Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. +This user isn't a [billable user](../../../subscriptions/self_managed/index.md#billable-users), +so it does not count toward the license limit count. + +In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` +as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), +these comments show the email of the user who sent the email. +This feature only applies to comments made in GitLab 16.1 and later. + +### Change the Support Bot's display name + +You can change the display name of the Support Bot user. Emails sent from Service Desk have +this name in the `From` header. The default display name is `GitLab Support Bot`. + +To edit the custom email display name: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email display name**, enter a new name. +1. Select **Save changes**. + +## Custom email address **(BETA)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329990) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `service_desk_custom_email`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.4. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for +your entire instance, an administrator can [disable the feature flag](../../../administration/feature_flags.md) +named `service_desk_custom_email`. On GitLab.com, this feature is available. + +Configure a custom email address to show as the sender of your support communication. +Maintain brand identity and instill confidence among support requesters with a domain they recognize. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [a short showcase video](https://youtu.be/_moD5U3xcQs). + +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). +A Beta feature is not production-ready, but is unlikely to change drastically +before it's released. We encourage users to try Beta features and provide feedback +in [the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/416637). + +### Prerequisites + +You can use one custom email address for Service Desk per project and it must be unique across the instance. + +The custom email address you want to use must meet all of the following requirements: + +- You can set up email forwarding. +- Forwarded emails preserve the original `From` header. +- Your service provider must support sub-addressing. An email address consists of a local part (everything before `@`) and a + domain part. + + With email sub-addressing you can create unique variations of an email address by adding a `+` symbol followed + by any text to the local part. Given the email address `support@example.com`, check whether sub-addressing is supported by + sending an email to `support+1@example.com`. This email should appear in your mailbox. +- You have SMTP credentials (ideally, you should use an app password). +- You must have at least the Maintainer role for the project. +- Service Desk must be configured for the project. + +### Configure a custom email address + +Configure and verify a custom email address when you want to send Service Desk emails using your own email address. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk** and find the **Custom email** settings. +1. Note the presented Service Desk address of this project, and with your email provider + (for example, Gmail), set up email forwarding from the custom email address to the + Service Desk address. +1. Back in GitLab, complete the fields. **SMTP host** must be resolvable from the network of your GitLab instance (on GitLab self-managed) + or the public internet (on GitLab SaaS). +1. Select **Save & test settings**. + +The configuration has been saved and the verification of the custom email address is triggered. + +#### Verification + +1. After completing the configuration, all project owners and the administrator that saved the custom email configuration receive a notification email. +1. A verification email is sent using the provided SMTP credentials to the custom email address (with a sub-addressing part). + The email contains a verification token. When email forwarding is set up correctly and all prerequisites are met, + the email is forwarded to your Service Desk address and ingested by GitLab. GitLab checks the following conditions: + 1. GitLab can send an email using the SMTP credentials. + 1. Sub-addressing is supported (with the `+verify` sub-addressing part). + 1. `From` header is preserved after forwarding. + 1. Verification token is correct. + 1. Email is received in 30 minutes. + +Typically the process takes only a few minutes. + +To cancel verification at any time or if it fails, select **Reset custom email**. +The settings page updates accordingly and reflects the current state of the verification. +The SMTP credentials are deleted and you can start the configuration again. + +On failure and success all project owners and the user who triggered the verification process receive a +notification email with the verification result. +If the verification failed, the email also contains details of the reason. + +If the verification was successful, the custom email address is ready to be used. +You can now enable sending Service Desk emails via the custom email address. + +### Enable or disable the custom email address + +After the custom email address has been verified, administrators can enable or disable sending Service Desk emails via the custom email address. + +To **enable** the custom email address: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn on the **Enable custom email** toggle. + Service Desk emails to external participants are sent using the SMTP credentials. + +To **disable** the custom email address: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Turn off the **Enable custom email** toggle. + Because you set up email forwarding, emails to your custom email address continue to be processed and + appear as Service Desk Tickets in your project. + + Service Desk emails to external participants are now sent using the GitLab instance's default outgoing + email configuration. + +### Change or remove custom email configuration + +To change the custom email configuration you must reset and remove it and configure custom email again. + +To reset the configuration at any step in the process, select **Reset custom email**. +The credentials are then removed from the database. + +### Custom email reply address + +External participants can [reply by email](../../../administration/reply_by_email.md) to Service Desk tickets. +GitLab uses an email reply address with a 32-character reply key that corresponds to the ticket. +When a custom email is configured, GitLab generates the reply address from that email. + +### Known issues + +- Some service providers don't allow SMTP connections any more. + Often you can enable them on a per user basis and create an app password. +- Microsoft Exchange doesn't preserve the `From` header, so you cannot use a custom email from the same tenant. + As a workaround: + - On GitLab SaaS, use a transport rule to forward emails from the custom email address to the Service Desk email + from GitLab SaaS. Forwarding to an email address outside the current tenant preserves the original `From` header. + - On GitLab self-managed, use a subdomain or a different domain from another service provider for the + custom email address or the GitLab instance `incoming_email` or `service_desk_email`. + +## Use an additional Service Desk alias email **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. + +You can use an additional alias email address for Service Desk on an instance level. + +To do this, you must configure +a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. + +### Configure Service Desk alias email + +NOTE: +On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. + +Service Desk uses the [incoming email](../../../administration/incoming_email.md) +configuration by default. However, to have a separate email address for Service Desk, +configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) +in project settings. + +Prerequisites: + +- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, + before the `@`. The placeholder is used to identify the project where the issue should be created. +- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes + to make sure Service Desk emails are processed correctly. + +To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +NOTE: +In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. +To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. +For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). +In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no +secret file configuration setting is needed. +For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). + +```ruby +gitlab_rails['service_desk_email_enabled'] = true +gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" +gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" +gitlab_rails['service_desk_email_password'] = "[REDACTED]" +gitlab_rails['service_desk_email_mailbox_name'] = "inbox" +gitlab_rails['service_desk_email_idle_timeout'] = 60 +gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" +gitlab_rails['service_desk_email_host'] = "imap.gmail.com" +gitlab_rails['service_desk_email_port'] = 993 +gitlab_rails['service_desk_email_ssl'] = true +gitlab_rails['service_desk_email_start_tls'] = false +``` + +:::TabTitle Self-compiled (source) + +```yaml +service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_contact@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + delivery_method: webhook + secret_file: .gitlab-mailroom-secret + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true +``` + +::EndTabs + +The configuration options are the same as for configuring +[incoming email](../../../administration/incoming_email.md#set-it-up). + +#### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../../administration/encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the Service Desk email secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +1. If initially your Service Desk configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + service_desk_email: + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +#### Microsoft Graph + +> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. +> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. + +`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft +Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph +[the same way as for incoming email](../../../administration/incoming_email.md#microsoft-graph). + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting + the values you want: + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```ruby + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): + + ```shell + kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> + ``` + +1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). + Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: + + ```shell + kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + serviceDeskEmail: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: inbox + inboxMethod: microsoft_graph + azureAdEndpoint: https://login.microsoftonline.com + graphEndpoint: https://graph.microsoft.com + tenantId: "YOUR-TENANT-ID" + clientId: "YOUR-CLIENT-ID" + clientSecret: + secret: service-desk-email-client-secret + key: secret + deliveryMethod: webhook + authToken: + secret: <name>-service-desk-email-auth-token + key: authToken + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: + + ```yaml + global: + appConfig: + serviceDeskEmail: + [..] + azureAdEndpoint: https://login.microsoftonline.us + graphEndpoint: https://graph.microsoft.us + [..] + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azure_ad_endpoint` and `graph_endpoint` settings: + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + azure_ad_endpoint: "https://login.microsoftonline.us" + graph_endpoint: "https://graph.microsoft.us" + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + +::EndTabs + +### Configure a suffix for Service Desk alias email + +You can set a custom suffix in your project's Service Desk settings. + +A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). + +When configured, the custom suffix creates a new Service Desk email address, consisting of the +`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` + +Prerequisites: + +- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Below **Email address suffix**, enter the suffix to use. +1. Select **Save changes**. + +For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: + +- Email address suffix is set to `support`. +- Service Desk email address is configured to `contact+%{key}@example.com`. + +The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. +The [incoming email](../../../administration/incoming_email.md) address still works. + +If you don't configure a custom suffix, the default project identification is used for identifying +the project. + +## Configure email ingestion in multi-node environments + +A multi-node environment is a setup where GitLab is run across multiple servers +for scalability, fault tolerance, and performance reasons. + +GitLab uses a separate process called `mail_room` to ingest new unread emails +from the `incoming_email` and `service_desk_email` mailboxes. + +### Helm chart (Kubernetes) + +The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is +the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the +[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) +and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). + +### Linux package (Omnibus) + +In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single +`rails` node (for example, `application_role`) +or completely separately. + +#### Set up all nodes + +1. Add basic configuration for `incoming_email` and `service_desk_email` on every node + to render email addresses in the web UI and in generated emails. + + Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_enabled'] = true + gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" + ``` + + ::EndTabs + +1. GitLab offers two methods to transport emails from `mail_room` to the GitLab +application. You can configure the `delivery_method` for each email setting individually: + 1. Recommended: `webhook` (default in GitLab 15.3 and later) sends the email payload via an API POST request to your GitLab + application. It uses a shared token to authenticate. If you choose this method, + make sure the `mail_room` process can access the API endpoint and distribute the shared + token across all application nodes. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + + gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + ::EndTabs + + 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): + If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['incoming_email_delivery_method'] = "sidekiq" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" + ``` + + ::EndTabs + +1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = false + ``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) for the changes to take effect. + +#### Set up a single email ingestion node + +After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. +This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and +move new unread emails to GitLab. + +1. Choose an existing node that additionally handles email ingestion. +1. Add [full configuration and credentials](../../../administration/incoming_email.md#configuration-examples) + for `incoming_email` and `service_desk_email`. +1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = true + ``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) on this node for the changes to take effect. diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md index 208e798bd21..ab807553436 100644 --- a/doc/user/project/service_desk/index.md +++ b/doc/user/project/service_desk/index.md @@ -39,870 +39,21 @@ Meanwhile: - Your team saves time by not having to leave GitLab (or set up integrations) to follow up with your customer. -## Configure Service Desk - -By default, Service Desk is active in new projects. -If it's not active, you can do it in the project's settings. - -Prerequisites: - -- You must have at least the Maintainer role for the project. -- On GitLab self-managed, you must [set up incoming email](../../../administration/incoming_email.md#set-it-up) - for the GitLab instance. You should use - [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), - but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). - To do this, you must have administrator access. -- You must have enabled [issue](../settings/index.md#configure-project-visibility-features-and-permissions) - tracker for the project. - -To enable Service Desk in your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Turn on the **Activate Service Desk** toggle. -1. Optional. Complete the fields. - - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. - - If the list below **Template to append to all Service Desk issues** is empty, create a - [description template](../description_templates.md) in your repository. -1. Select **Save changes**. - -Service Desk is now enabled for this project. -If anyone sends an email to the address available below **Email address to use for Service Desk**, -GitLab creates a confidential issue with the email's content. - -### Improve your project's security - -To improve your Service Desk project's security, you should: - -- Put the Service Desk email address behind an alias on your email system so you can change it later. -- [Enable Akismet](../../../integration/akismet.md) on your GitLab instance to add spam checking to this service. - Unblocked email spam can result in many spam issues being created. - -### Customize emails sent to the requester - -> - Moved from GitLab Premium to GitLab Free in 13.2. -> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. -> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. -> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. - -An email is sent to the requester when: - -- A requester submits a new ticket by emailing Service Desk. -- A new public comment is added on a Service Desk ticket. - - Editing a comment does not trigger a new email to be sent. - -You can customize the body of these email messages with Service Desk email templates. The templates -can include [GitLab Flavored Markdown](../../markdown.md) and [some HTML tags](../../markdown.md#inline-html). -For example, you can format the emails to include a header and footer in accordance with your -organization's brand guidelines. You can also include the following placeholders to display dynamic -content specific to the Service Desk ticket or your GitLab instance. - -| Placeholder | `thank_you.md` | `new_note.md` | Description -| ---------------------- | ---------------------- | ---------------------- | ----------- -| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. -| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. -| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). -| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. -| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. -| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. - -#### Thank you email - -When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. -Without additional configuration, GitLab sends the default thank you email. - -To create a custom thank you email template: - -1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. -1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), - [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the reply - to Service Desk requesters. - -#### New note email - -When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. -Without additional configuration, GitLab sends the content of the comment. - -To keep your emails on brand, you can create a custom new note email template. To do so: - -1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. -1. Populate the Markdown file with text, [GitLab Flavored Markdown](../../markdown.md), - [some selected HTML tags](../../markdown.md#inline-html), and placeholders to customize the new note - email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can - read the contents of the comment. - -#### Instance-level email header, footer, and additional text **(FREE SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. - -Instance administrators can add a header, footer or additional text to the GitLab instance and apply -them to all emails sent from GitLab. If you're using a custom `thank_you.md` or `new_note.md`, to include -this content, add `%{SYSTEM_HEADER}`, `%{SYSTEM_FOOTER}`, or `%{ADDITIONAL_TEXT}` to your templates. - -For more information, see [System header and footer messages](../../../administration/appearance.md#system-header-and-footer-messages) and [custom additional text](../../../administration/settings/email.md#custom-additional-text). - -### Use a custom template for Service Desk tickets - -You can select one [description template](../description_templates.md#create-an-issue-template) -**per project** to be appended to every new Service Desk ticket's description. - -You can set description templates at various levels: - -- The entire [instance](../description_templates.md#set-instance-level-description-templates). -- A specific [group or subgroup](../description_templates.md#set-group-level-description-templates). -- A specific [project](../description_templates.md#set-a-default-template-for-merge-requests-and-issues). - -The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. - -Prerequisite: - -- You must have [created a description template](../description_templates.md#create-an-issue-template). - -To use a custom description template with Service Desk: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. - -### Support Bot user - -Behind the scenes, Service Desk works by the special Support Bot user creating issues. -This user isn't a [billable user](../../../subscriptions/self_managed/index.md#billable-users), -so it does not count toward the license limit count. - -In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` -as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), -these comments show the email of the user who sent the email. -This feature only applies to comments made in GitLab 16.1 and later. - -#### Change the Support Bot's display name - -You can change the display name of the Support Bot user. Emails sent from Service Desk have -this name in the `From` header. The default display name is `GitLab Support Bot`. - -To edit the custom email display name: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Below **Email display name**, enter a new name. -1. Select **Save changes**. - -### Use an additional Service Desk alias email **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. - -You can use an additional alias email address for Service Desk on an instance level. - -To do this, you must configure -a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a -[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. - -#### Configure Service Desk alias email - -NOTE: -On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the -[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. - -Service Desk uses the [incoming email](../../../administration/incoming_email.md) -configuration by default. However, to have a separate email address for Service Desk, -configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) -in project settings. - -Prerequisites: - -- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, - before the `@`. The placeholder is used to identify the project where the issue should be created. -- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes - to make sure Service Desk emails are processed correctly. - -To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -NOTE: -In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. -To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. -For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). -In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no -secret file configuration setting is needed. -For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). - -```ruby -gitlab_rails['service_desk_email_enabled'] = true -gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" -gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" -gitlab_rails['service_desk_email_password'] = "[REDACTED]" -gitlab_rails['service_desk_email_mailbox_name'] = "inbox" -gitlab_rails['service_desk_email_idle_timeout'] = 60 -gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" -gitlab_rails['service_desk_email_host'] = "imap.gmail.com" -gitlab_rails['service_desk_email_port'] = 993 -gitlab_rails['service_desk_email_ssl'] = true -gitlab_rails['service_desk_email_start_tls'] = false -``` - -:::TabTitle Self-compiled (source) - -```yaml -service_desk_email: - enabled: true - address: "project_contact+%{key}@example.com" - user: "project_contact@example.com" - password: "[REDACTED]" - host: "imap.gmail.com" - delivery_method: webhook - secret_file: .gitlab-mailroom-secret - port: 993 - ssl: true - start_tls: false - log_path: "log/mailroom.log" - mailbox: "inbox" - idle_timeout: 60 - expunge_deleted: true -``` - -::EndTabs - -The configuration options are the same as for configuring -[incoming email](../../../administration/incoming_email.md#set-it-up). - -##### Use encrypted credentials - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. - -Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally -use an encrypted file for the incoming email credentials. - -Prerequisites: - -- To use encrypted credentials, you must first enable the - [encrypted configuration](../../../administration/encrypted_configuration.md). - -The supported configuration items for the encrypted file are: - -- `user` -- `password` - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: - - ```ruby - gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" - gitlab_rails['service_desk_email_password'] = "examplepassword" - ``` - -1. Edit the encrypted secret: - - ```shell - sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim - ``` - -1. Enter the unencrypted contents of the Service Desk email secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -:::TabTitle Helm chart (Kubernetes) - -Use a Kubernetes secret to store the Service Desk email password. For more information, -read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). - -:::TabTitle Docker - -1. If initially your Service Desk configuration in `docker-compose.yml` looked like: - - ```yaml - version: "3.6" - services: - gitlab: - image: 'gitlab/gitlab-ee:latest' - restart: always - hostname: 'gitlab.example.com' - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" - gitlab_rails['service_desk_email_password'] = "examplepassword" - ``` - -1. Get inside the container, and edit the encrypted secret: - - ```shell - sudo docker exec -t <container_name> bash - gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor - ``` - -1. Enter the unencrypted contents of the Service Desk secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -:::TabTitle Self-compiled (source) - -1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: - - ```yaml - production: - service_desk_email: - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit the encrypted secret: - - ```shell - bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production - ``` - -1. Enter the unencrypted contents of the Service Desk secret: - - ```yaml - user: 'service-desk-email@mail.example.com' - password: 'examplepassword' - ``` - -1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. -1. Save the file and restart GitLab and Mailroom - - ```shell - # For systems running systemd - sudo systemctl restart gitlab.target - - # For systems running SysV init - sudo service gitlab restart - ``` - -::EndTabs - -##### Microsoft Graph - -> - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. -> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. - -`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph -[the same way as for incoming email](../../../administration/incoming_email.md#microsoft-graph). - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting - the values you want: - - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), - configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: - - ```ruby - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -:::TabTitle Helm chart (Kubernetes) - -1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): - - ```shell - kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> - ``` - -1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). - Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: - - ```shell - kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) - ``` - -1. Export the Helm values: - - ```shell - helm get values gitlab > gitlab_values.yaml - ``` - -1. Edit `gitlab_values.yaml`: - - ```yaml - global: - appConfig: - serviceDeskEmail: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: inbox - inboxMethod: microsoft_graph - azureAdEndpoint: https://login.microsoftonline.com - graphEndpoint: https://graph.microsoft.com - tenantId: "YOUR-TENANT-ID" - clientId: "YOUR-CLIENT-ID" - clientSecret: - secret: service-desk-email-client-secret - key: secret - deliveryMethod: webhook - authToken: - secret: <name>-service-desk-email-auth-token - key: authToken - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: - - ```yaml - global: - appConfig: - serviceDeskEmail: - [..] - azureAdEndpoint: https://login.microsoftonline.us - graphEndpoint: https://graph.microsoft.us - [..] - ``` - -1. Save the file and apply the new values: - - ```shell - helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab - ``` - -:::TabTitle Docker - -1. Edit `docker-compose.yml`: - - ```yaml - version: "3.6" - services: - gitlab: - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azure_ad_endpoint` and `graph_endpoint` settings: - -1. Edit `docker-compose.yml`: - - ```yaml - version: "3.6" - services: - gitlab: - environment: - GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional - } - ``` - -1. Save the file and restart GitLab: - - ```shell - docker compose up -d - ``` - -:::TabTitle Self-compiled (source) - -1. Edit `/home/git/gitlab/config/gitlab.yml`: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: "inbox" - delivery_method: webhook - log_path: "log/mailroom.log" - secret_file: .gitlab-mailroom-secret - inbox_method: "microsoft_graph" - inbox_options: - tenant_id: "<YOUR-TENANT-ID>" - client_id: "<YOUR-CLIENT-ID>" - client_secret: "<YOUR-CLIENT-SECRET>" - poll_interval: 60 # Optional - ``` - - For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), - configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.onmicrosoft.com" - user: "project_contact@example.onmicrosoft.com" - mailbox: "inbox" - delivery_method: webhook - log_path: "log/mailroom.log" - secret_file: .gitlab-mailroom-secret - inbox_method: "microsoft_graph" - inbox_options: - azure_ad_endpoint: "https://login.microsoftonline.us" - graph_endpoint: "https://graph.microsoft.us" - tenant_id: "<YOUR-TENANT-ID>" - client_id: "<YOUR-CLIENT-ID>" - client_secret: "<YOUR-CLIENT-SECRET>" - poll_interval: 60 # Optional - ``` - -::EndTabs - -#### Configure a suffix for Service Desk alias email - -You can set a custom suffix in your project's Service Desk settings. - -A suffix can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). - -When configured, the custom suffix creates a new Service Desk email address, consisting of the -`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` - -Prerequisites: - -- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Service Desk**. -1. Below **Email address suffix**, enter the suffix to use. -1. Select **Save changes**. - -For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: - -- Email address suffix is set to `support`. -- Service Desk email address is configured to `contact+%{key}@example.com`. - -The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. -The [incoming email](../../../administration/incoming_email.md) address still works. - -If you don't configure a custom suffix, the default project identification is used for identifying -the project. - -### Configure email ingestion in multi-node environments - -A multi-node environment is a setup where GitLab is run across multiple servers -for scalability, fault tolerance, and performance reasons. - -GitLab uses a separate process called `mail_room` to ingest new unread emails -from the `incoming_email` and `service_desk_email` mailboxes. - -#### Helm chart (Kubernetes) - -The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is -the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the -[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) -and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). - -#### Linux package (Omnibus) - -In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single -`rails` node (for example, `application_role`) -or completely separately. - -##### Set up all nodes - -1. Add basic configuration for `incoming_email` and `service_desk_email` on every node - to render email addresses in the web UI and in generated emails. - - Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - gitlab_rails['incoming_email_enabled'] = true - gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" - ``` - - ::EndTabs - -1. GitLab offers two methods to transport emails from `mail_room` to the GitLab -application. You can configure the `delivery_method` for each email setting individually: - 1. Recommended: `webhook` (default in GitLab 15.3 and later) sends the email payload via an API POST request to your GitLab - application. It uses a shared token to authenticate. If you choose this method, - make sure the `mail_room` process can access the API endpoint and distribute the shared - token across all application nodes. - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - gitlab_rails['incoming_email_delivery_method'] = "webhook" - - # The URL that mail_room can contact. You can also use an internal URL or IP, - # just make sure mail_room can access the GitLab API via that address. - # Do not end with "/". - gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" - - # The shared secret file that should contain a random token. Make sure it's the same on every node. - gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - gitlab_rails['service_desk_email_delivery_method'] = "webhook" - - # The URL that mail_room can contact. You can also use an internal URL or IP, - # just make sure mail_room can access the GitLab API via that address. - # Do not end with "/". - - gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" - - # The shared secret file that should contain a random token. Make sure it's the same on every node. - gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" - ``` - - ::EndTabs - - 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): - If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. - - ::Tabs - - :::TabTitle `incoming_email` - - ```ruby - # It uses the Redis configuration to directly add Sidekiq jobs - gitlab_rails['incoming_email_delivery_method'] = "sidekiq" - ``` - - :::TabTitle `service_desk_email` - - ```ruby - # It uses the Redis configuration to directly add Sidekiq jobs - gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" - ``` - - ::EndTabs - -1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: - - ```ruby - mailroom['enabled'] = false - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) for the changes to take effect. - -##### Set up a single email ingestion node - -After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. -This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and -move new unread emails to GitLab. - -1. Choose an existing node that additionally handles email ingestion. -1. Add [full configuration and credentials](../../../administration/incoming_email.md#configuration-examples) - for `incoming_email` and `service_desk_email`. -1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: - - ```ruby - mailroom['enabled'] = true - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md) on this node for the changes to take effect. - -## Use Service Desk - -You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). -In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). - -### View Service Desk email address - -To check what the Service Desk email address is for your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Monitor > Service Desk**. - -The email address is available at the top of the issue list. - -### As an end user (issue creator) - -> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. - -To create a Service Desk issue, an end user does not need to know anything about -the GitLab instance. They just send an email to the address they are given, and -receive an email back confirming receipt: - - - -This also gives the end user an option to unsubscribe. - -If they don't choose to unsubscribe, then any new comments added to the issue -are sent as emails: - - - -Any responses they send via email are displayed in the issue itself. - -For information about headers used for treating email, see -[the incoming email documentation](../../../administration/incoming_email.md#accepted-headers). - -### As a responder to the issue - -For responders to the issue, everything works just like other GitLab issues. -GitLab displays a familiar-looking issue tracker where responders can see -issues created through customer support requests, and filter or interact with them. - - - -Messages from the end user are shown as coming from the special -[Support Bot user](../../../subscriptions/self_managed/index.md#billable-users). -You can read and write comments as you usually do in GitLab: - - - -- The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, is shown in emails. - -#### View Service Desk issues - -Prerequisites: - -- You must have at least the Reporter role for the project. - -To view Service Desk issues: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Monitor > Service Desk**. - -### Email contents and formatting - -#### Special HTML formatting in HTML emails - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. - -HTML emails show HTML formatting, such as: - -- Tables -- Blockquotes -- Images -- Collapsible sections - -#### Files attached to comments - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. -On GitLab.com, this feature is available. - -If a comment contains any attachments and their total size is less than or equal to 10 MB, these -attachments are sent as part of the email. In other cases, the email contains links to the attachments. - -In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. - -## Privacy considerations - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. - -Service Desk issues are [confidential](../issues/confidential_issues.md), so they are -only visible to project members. The project owner can -[make an issue public](../issues/confidential_issues.md#in-an-existing-issue). -When a Service Desk issue becomes public, the issue creator's and participants' email addresses are -visible to signed-in users with at least the Reporter role for the project. - -In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email -address is disclosed to everyone who can view the project. - -Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless -of their role** in the project. - -The unique internal email address is visible to project members at least -the Reporter role in your GitLab instance. -An external user (issue creator) cannot see the internal email address -displayed in the information note. - -### Moving a Service Desk issue - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. - -You can move a Service Desk issue the same way you -[move a regular issue](../issues/managing_issues.md#move-an-issue) in GitLab. - -If a Service Desk issue is moved to a different project with Service Desk enabled, -the customer who created the issue continues to receive email notifications. -Because a moved issue is first closed, then copied, the customer is considered to be a participant -in both issues. They continue to receive any notifications in the old issue and the new one. +## Related topics + +- [Configure Service Desk](configure.md) + - [Improve your project's security](configure.md#improve-your-projects-security) + - [Customize emails sent to the requester](configure.md#customize-emails-sent-to-the-requester) + - [Use a custom template for Service Desk tickets](configure.md#use-a-custom-template-for-service-desk-tickets) + - [Support Bot user](configure.md#support-bot-user) + - [Custom email address (Beta)](configure.md#custom-email-address) + - [Use an additional Service Desk alias email](configure.md#use-an-additional-service-desk-alias-email) + - [Configure email ingestion in multi-node environments](configure.md#configure-email-ingestion-in-multi-node-environments) +- [Use Service Desk](using_service_desk.md#use-service-desk) + - [As an end user (issue creator)](using_service_desk.md#as-an-end-user-issue-creator) + - [As a responder to the issue](using_service_desk.md#as-a-responder-to-the-issue) + - [Email contents and formatting](using_service_desk.md#email-contents-and-formatting) + - [Privacy considerations](using_service_desk.md#privacy-considerations) ## Troubleshooting Service Desk diff --git a/doc/user/project/service_desk/using_service_desk.md b/doc/user/project/service_desk/using_service_desk.md new file mode 100644 index 00000000000..73d85d418d9 --- /dev/null +++ b/doc/user/project/service_desk/using_service_desk.md @@ -0,0 +1,182 @@ +--- +stage: Monitor +group: Respond +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Use Service Desk **(FREE ALL)** + +You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). +In these issues, you can also see our friendly neighborhood [Support Bot](configure.md#support-bot-user). + +## View Service Desk email address + +To check what the Service Desk email address is for your project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. + +The email address is available at the top of the issue list. + +## As an end user (issue creator) + +> Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. In earlier versions, the Service Desk email address had to be in the "To" field. + +To create a Service Desk issue, an end user does not need to know anything about +the GitLab instance. They just send an email to the address they are given, and +receive an email back confirming receipt: + + + +This also gives the end user an option to unsubscribe. + +If they don't choose to unsubscribe, then any new comments added to the issue +are sent as emails: + + + +Any responses they send via email are displayed in the issue itself. + +For information about headers used for treating email, see +[the incoming email documentation](../../../administration/incoming_email.md#accepted-headers). + +## As a responder to the issue + +For responders to the issue, everything works just like other GitLab issues. +GitLab displays a familiar-looking issue tracker where responders can see +issues created through customer support requests, and filter or interact with them. + + + +Messages from the end user are shown as coming from the special +[Support Bot user](../../../subscriptions/self_managed/index.md#billable-users). +You can read and write comments as you usually do in GitLab: + + + +- The project's visibility (private, internal, public) does not affect Service Desk. +- The path to the project, including its group or namespace, is shown in emails. + +### View Service Desk issues + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To view Service Desk issues: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. + +#### Redesigned issue list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413092) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `service_desk_vue_list`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `service_desk_vue_list`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +When this feature is enabled, the Service Desk issue list more closely matches the regular issue list. +Available features include: + +- The same sorting and ordering options [as on the issue list](../issues/sorting_issue_lists.md). +- The same filters, including [the OR operator](#filter-with-the-or-operator) and [filtering by issue ID](#filter-issues-by-id). + +There is no longer an option to create a new issue from the Service Desk issue list. +This decision better reflects the nature of Service Desk, where new issues are created by emailing +a dedicated email address. + +##### Filter the list of issues + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. +1. Above the list of issues, select **Search or filter results...**. +1. In the dropdown list that appears, select the attribute you want to filter by. +1. Select or type the operator to use for filtering the attribute. The following operators are + available: + - `=`: Is + - `!=`: Is not one of +1. Enter the text to filter the attribute by. + You can filter some attributes by **None** or **Any**. +1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical + `AND`. + +##### Filter with the OR operator + +When [filtering with the OR operator](../issues/managing_issues.md#filter-with-the-or-operator) is enabled, +you can use **is one of: `||`** +when you [filter the list of issues](#filter-the-list-of-issues) by: + +- Assignees +- Labels + +`is one of` represents an inclusive OR. For example, if you filter by `Assignee is one of Sidney Jones` and +`Assignee is one of Zhang Wei`, GitLab shows issues where either `Sidney`, `Zhang`, or both of them are assignees. + +##### Filter issues by ID + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Monitor > Service Desk**. +1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. + +## Email contents and formatting + +### Special HTML formatting in HTML emails + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. + +HTML emails show HTML formatting, such as: + +- Tables +- Blockquotes +- Images +- Collapsible sections + +### Files attached to comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + +In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. + +## Privacy considerations + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. + +Service Desk issues are [confidential](../issues/confidential_issues.md), so they are +only visible to project members. The project owner can +[make an issue public](../issues/confidential_issues.md#in-an-existing-issue). +When a Service Desk issue becomes public, the issue creator's and participants' email addresses are +visible to signed-in users with at least the Reporter role for the project. + +In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email +address is disclosed to everyone who can view the project. + +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their role** in the project. + +The unique internal email address is visible to project members at least +the Reporter role in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. + +### Moving a Service Desk issue + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. + +You can move a Service Desk issue the same way you +[move a regular issue](../issues/managing_issues.md#move-an-issue) in GitLab. + +If a Service Desk issue is moved to a different project with Service Desk enabled, +the customer who created the issue continues to receive email notifications. +Because a moved issue is first closed, then copied, the customer is considered to be a participant +in both issues. They continue to receive any notifications in the old issue and the new one. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 087330431ad..22eb7c54d12 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -79,14 +79,14 @@ For example: Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: -1. [Enable file exports](../../../administration/settings/visibility_and_access_controls.md#enable-project-export) on the source +1. [Enable file exports](../../../administration/settings/import_and_export_settings.md#enable-project-export) on the source instance. 1. Enable file exports as an import source for the destination instance. On GitLab.com, file exports are already enabled as an import source. To enable file exports as an import source for the destination instance: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. @@ -113,7 +113,7 @@ Prerequisites: To export a project and its data, follow these steps: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Export project**. @@ -245,7 +245,7 @@ If you have a larger project, consider [using a Rake task](../../../administrati Administrators can set the maximum import file size one of two ways: - With the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings). -- In the [Admin Area UI](../../../administration/settings/account_and_limit_settings.md#max-import-size). +- In the [Admin Area UI](../../../administration/settings/import_and_export_settings.md#max-import-size). The default is `0` (unlimited). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 6c2140595d9..d9c114c0a59 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -11,9 +11,11 @@ Use the **Settings** page to manage the configuration options in your [project]( ## View project settings -You must have at least the Maintainer role to view project settings. +Prerequisite: + +- You must have at least the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. To display all settings in a section, select **Expand**. 1. Optional. Use the search box to find a setting. @@ -22,8 +24,11 @@ You must have at least the Maintainer role to view project settings. Use the project general settings to edit your project details. -1. Sign in to GitLab with at least the Maintainer role. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +Prerequisite: + +- You must have at least the Maintainer role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. In the **Project name** text box, enter your project name. 1. In the **Project description** text box, enter your project description. @@ -31,11 +36,11 @@ Use the project general settings to edit your project details. ## Assign topics to a project -Use topics to categorize projects and find similar new projects. +Use [topics](../working_with_projects.md#organizing-projects-with-topics) to categorize projects and find similar new projects. To assign topics to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings** > **General**. 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. @@ -46,50 +51,38 @@ If you're an instance administrator, you can administer all project topics from NOTE: The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. -## Add a compliance framework to a project **(PREMIUM ALL)** +## Rename a repository + +A project's repository name defines its URL and its place on the file disk +where GitLab is installed. + +Prerequisite: -You can -[add compliance frameworks to projects](../../group/compliance_frameworks.md#add-a-compliance-framework-to-a-project) -in a group that has a compliance framework. +- You must be an administrator or have the Maintainer or Owner role for the project. + +NOTE: +When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see +[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). + +To rename a repository: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Change path** text box, edit the path. +1. Select **Change path**. -## Configure project visibility, features, and permissions +## Configure project features and permissions -To configure visibility, features, and permissions for a project: +To configure features and permissions for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. -1. To change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. 1. To allow users to request access to the project, select the **Users can request access** checkbox. -1. Use the [toggles](#project-feature-settings) to enable or disable features in the project. +1. To enable or disable features in the project, use the feature toggles. 1. Select **Save changes**. -### Project feature settings - -Use the toggles to enable or disable features in the project. - -| Option | More access limit options | Description -| :------------------------------- | :------------------------ | :---------- | -| **Issues** | **{check-circle}** Yes | Activates the GitLab issues tracker. -| **Repository** | **{check-circle}** Yes | Enables [repository](../repository/index.md) functionality. -| **Merge requests** | **{check-circle}** Yes | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). -| **Forks** | **{check-circle}** Yes | Enables [forking](../repository/forking_workflow.md) functionality. -| **Git Large File Storage (LFS)** | **{dotted-circle}** No | Enables the use of [large files](../../../topics/git/lfs/index.md). -| **Packages** | **{dotted-circle}** No | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. -| **CI/CD** | **{check-circle}** Yes | Enables [CI/CD](../../../ci/index.md) functionality. -| **Container Registry** | **{dotted-circle}** No | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. -| **Analytics** | **{check-circle}** Yes | Enables [analytics](../../analytics/index.md). -| **Requirements** | **{check-circle}** Yes | Control access to [Requirements Management](../requirements/index.md). -| **Security and Compliance** | **{check-circle}** Yes | Control access to [security features](../../application_security/index.md). -| **Wiki** | **{check-circle}** Yes | Enables a separate system for [documentation](../wiki/index.md). -| **Snippets** | **{check-circle}** Yes | Enables [sharing of code and text](../../snippets.md). -| **Pages** | **{check-circle}** Yes | Allows you to [publish static websites](../pages/index.md). -| **Releases** | **{check-circle}** Yes | Control access to [Releases](../releases/index.md). -| **Environments** | **{check-circle}** Yes | Control access to [Environments and Deployments](../../../ci/environments/index.md). -| **Feature flags** | **{check-circle}** Yes | Control access to [Feature flags](../../../operations/feature_flags.md). -| **Monitor** | **{check-circle}** Yes | Control access to [Monitor](../../../operations/index.md) features. -| **Infrastructure** | **{check-circle}** Yes | Control access to [Infrastructure](../../infrastructure/index.md) features. - When you disable a feature, the following additional features are also disabled: - If you disable the **Issues** feature, project users cannot use: @@ -111,164 +104,66 @@ When you disable a feature, the following additional features are also disabled: - **Git Large File Storage** - **Packages** -- Metrics dashboard access requires reading project environments and deployments. +- The metrics dashboard requires read access to project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. -### Manage project access through LDAP groups - -You can [use LDAP to manage group membership](../../group/access_and_permissions.md#manage-group-memberships-via-ldap). - -You cannot use LDAP groups to manage project access, but you can use the following -workaround. - -Prerequisites: - -- You must [integrate LDAP with GitLab](../../../administration/auth/ldap/index.md). -- You must be an administrator. - -1. [Create a group](../../group/index.md#create-a-group) to track membership of your project. -1. [Set up LDAP synchronization](../../../administration/auth/ldap/ldap_synchronization.md) for that group. -1. To use LDAP groups to manage access to a project, [add the LDAP-synchronized group as a member](../members/index.md#add-groups-to-a-project) - to the project. - -## Disable CVE identifier request in issues **(FREE SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. - -In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. - -To disable the CVE identifier request option in issues in your project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. -1. Select **Save changes**. - -## Disable project email notifications - -Prerequisites: - -- You must be an Owner of the project to disable email notifications related to the project. - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Clear the **Disable email notifications** checkbox. - ## Configure merge request settings for a project Configure your project's merge request settings: - Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). - Add merge request [description templates](../description_templates.md). -- Enable [merge request approvals](../merge_requests/approvals/index.md). -- Enable [status checks](../merge_requests/status_checks.md). -- Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). -- Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). -- Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). -- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -- Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). -- Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. -- Enable [Suggested Reviewers](../merge_requests/reviews/index.md#suggested-reviewers). - -## Service Desk - -Enable [Service Desk](../service_desk/index.md) for your project to offer customer support. - -## Export project - -Learn how to [export a project](import_export.md#import-a-project-and-its-data) in GitLab. - -## Advanced project settings - -Use the advanced settings to archive, rename, transfer, -[remove a fork relationship](../repository/forking_workflow.md#unlink-a-fork), or delete a project. - -### Archive a project - -When you archive a project, the repository, packages, issues, merge requests, and all -other features are read-only. Archived projects are also hidden from project listings. - -To archive a project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Archive project** section, select **Archive project**. -1. To confirm, select **OK**. - -### Unarchive a project - -When you unarchive a project, you remove the read-only restriction and make it -available in project lists. - -Prerequisites: - -- To unarchive a project, you must be an administrator or a project Owner. - -1. Find the archived project. - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **View all your projects**. - 1. Select **Explore projects**. - 1. In the **Sort projects** dropdown list, select **Show archived projects**. - 1. In the **Filter by name** field, enter the project name. - 1. Select the project link. -1. On the left sidebar, select **Settings > General**. -1. Under **Advanced**, select **Expand**. -1. In the **Unarchive project** section, select **Unarchive project**. -1. To confirm, select **OK**. - -### Rename a repository - -A project's repository name defines its URL and its place on the file disk -where GitLab is installed. - -Prerequisites: - -You must be a project maintainer, owner, or administrator to rename a repository. - -NOTE: -When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see -[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). - -To rename a repository: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Change path** text box, edit the path. -1. Select **Change path**. - -## Delete the source branch on merge by default +- Enable: + - [Merge request approvals](../merge_requests/approvals/index.md). + - [Status checks](../merge_requests/status_checks.md). + - [Merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). + - [Merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). + - [Required associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). + - [GitLab Duo Suggested Reviewers](../merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) + - [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). +- Configure: + - [Suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + - [Merge and squash commit message templates](../merge_requests/commit_templates.md). + - [Default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. + +### Delete the source branch on merge by default In merge requests, you can change the default behavior so that the **Delete the source branch** checkbox is always selected. To set this default: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. 1. Select **Enable "Delete source branch" option by default**. 1. Select **Save changes**. +## Export project + +You can [export a project and its data](import_export.md#export-a-project-and-its-data). + ## Transfer a project to another namespace When you transfer a project to another namespace, you move the project to a different group. Prerequisites: -- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) to which you are transferring. +- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) you are transferring to. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). -- Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. -- If a security policy is assigned to the project, it is automatically unassigned during the transfer. +- The project must not have a security policy. + If a security policy is assigned to the project, it is automatically unassigned during the transfer. +- If the root namespace changes, you must remove npm packages that follow the [naming convention](../../../user/packages/npm_registry/index.md#naming-convention) from the project. + After you transfer the project you can either: + + - Update the package scope with the new root namespace path, and publish it again to the project. + - Republish the package to the project without updating the root namespace path, which causes the package to no longer follow the naming convention. + If you republish the package without updating the root namespace path, it will not be available at the [instance level endpoint](../../../user/packages/npm_registry/index.md#install-from-the-instance-level). To transfer a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. Under **Transfer project**, choose the namespace to transfer the project to. @@ -283,12 +178,46 @@ to move any project to any namespace. ### Transferring a GitLab SaaS project to a different subscription tier -When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free, the following paid feature data is deleted: +When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free: -- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked +- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked. - [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) and [test cases](../../../ci/test_cases/index.md) are deleted. +## Archive a project + +When you archive a project, the repository, packages, issues, merge requests, and all +other features become read-only. Archived projects are also hidden from project lists. + +To archive a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Archive project** section, select **Archive project**. +1. To confirm, select **OK**. + +## Unarchive a project + +When you unarchive a project, the read-only restriction is removed, +and the project becomes available in project lists. + +Prerequisite: + +- You must be an administrator or have the Owner role for the project. + +1. Find the archived project. + 1. On the left sidebar, select **Search or go to**. + 1. Select **View all my projects**. + 1. Select **Explore projects**. + 1. In the **Sort projects** dropdown list, select **Show archived projects**. + 1. In the **Filter by name** field, enter the project name. + 1. Select the project link. +1. On the left sidebar, select **Settings > General**. +1. Under **Advanced**, select **Expand**. +1. In the **Unarchive project** section, select **Unarchive project**. +1. To confirm, select **OK**. + ## Delete a project > - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. @@ -297,6 +226,10 @@ When you transfer a project from a namespace licensed for GitLab SaaS Premium or > - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. You can mark a project to be deleted. +After you delete a project: + +- Projects in personal namespaces are deleted immediately. +- Projects in groups are deleted after a retention period. Prerequisite: @@ -304,7 +237,7 @@ Prerequisite: To delete a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Delete this project** section, select **Delete project**. @@ -312,6 +245,8 @@ To delete a project: This action deletes the project and all associated resources (such as issues and merge requests). +You can also [delete projects using the Rails console](../working_with_projects.md#delete-a-project-using-console). + ### Delayed project deletion **(PREMIUM ALL)** > - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. @@ -323,6 +258,10 @@ Projects in a group (not a personal namespace) can be deleted after a delay peri On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. On SaaS, there is a non-adjustable default retention period of seven days. +You can [view projects that are pending deletion](../working_with_projects.md#view-projects-pending-deletion), +and use the Rails console to +[find projects that are pending deletion](../working_with_projects.md#find-projects-that-are-pending-deletion). + ### Delete a project immediately > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. @@ -340,7 +279,7 @@ Prerequisites: To immediately delete a project marked for deletion: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Delete this project** section, select **Delete project**. @@ -352,39 +291,55 @@ To immediately delete a project marked for deletion: To restore a project marked for deletion: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the Restore project section, select **Restore project**. -## Monitor settings +## Disable project analytics -### Alerts +By default, [analytics for a project](../../analytics/index.md#project-level-analytics) are displayed under the **Analyze** item in the left sidebar. +To disable this feature and remove the **Analyze** item from the left sidebar: -Configure [alert integrations](../../../operations/incident_management/integrations.md#configuration) to triage and manage critical problems in your application as [alerts](../../../operations/incident_management/alerts.md). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn off the **Analytics** toggle. +1. Select **Save changes**. -### Incidents +## Disable CVE identifier request in issues **(FREE SAAS)** -#### Alert integration +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -Automatically [create](../../../operations/incident_management/alerts.md#trigger-actions-from-alerts), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. +In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. -#### PagerDuty integration +To disable the CVE identifier request option in issues in your project: -[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. +1. Select **Save changes**. -#### Incident settings +## Disable project email notifications -[Manage Service Level Agreements for incidents](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) with an SLA countdown timer. +Prerequisite: -### Error Tracking +- You must have the Owner role for the project. -Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Clear the **Disable email notifications** checkbox. -### Status Page **(ULTIMATE ALL)** +## Related topics -[Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) -to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). +- [Alert integrations](../../../operations/incident_management/integrations.md#configuration) +- [PagerDuty incident management](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook) +- [SLA countdown timer](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) +- [Error tracking](../../../operations/error_tracking.md) +- [Incidents sync](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) +- [Service Desk](../service_desk/index.md) ## Troubleshooting diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 78620eb2ab3..29d57328532 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Authentication and Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, howto @@ -55,7 +55,7 @@ all projects that have visibility level set to [Internal](../../public_access.md To create a project access token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Enter an expiry date for the token. @@ -73,12 +73,14 @@ A project access token is displayed. Save the project access token somewhere saf To revoke a project access token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. 1. Next to the project access token to revoke, select **Revoke**. ## Scopes for a project access token +> `k8s_proxy` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422408) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `k8s_proxy_pat`. Enabled by default. + The scope determines the actions you can perform when you authenticate with a project access token. NOTE: @@ -93,6 +95,8 @@ See the warning in [create a project access token](#create-a-project-access-toke | `read_repository` | Grants read access (pull) to the repository. | | `write_repository` | Grants read and write access (pull and push) to the repository. | | `create_runner` | Grants permission to create runners in the project. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project. | ## Enable or disable project access token creation @@ -100,7 +104,7 @@ See the warning in [create a project access token](#create-a-project-access-toke To enable or disable project access token creation for all projects in a top-level group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Allow project and group access token creation**. diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 84ff9efbd14..661f10290c6 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -31,7 +31,7 @@ The filtering options are: ### On an epic -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Epics**. 1. Identify your desired epic, and select its title. 1. Go to the **Activity** section. @@ -39,14 +39,14 @@ The filtering options are: ### On an issue -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Plan > Issues** and find your issue. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. ### On a merge request -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index ec8d886c68e..f9a11a51c98 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -185,7 +185,7 @@ The following time units are available: In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 994ed244832..fb2bd707c56 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -23,7 +23,7 @@ To pair the Web IDE with a remote development environment, see [remote developme To open the Web IDE from the GitLab UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Use the <kbd>.</kbd> keyboard shortcut. You can also open the Web IDE from: @@ -81,6 +81,20 @@ To view a list of files you changed in the Web IDE: Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. For more information, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). +## Restore uncommitted changes + +You don't have to manually save any file you modify in the Web IDE. +Modified files are automatically staged and can be [committed](#commit-changes). +Uncommitted changes are saved in your browser's local storage and persist +even if you close the browser tab or refresh the Web IDE. + +If your uncommitted changes are not available, you can restore the changes from local history. +To restore uncommitted changes in the Web IDE: + +1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd>. +1. In the search box, enter `Local History: Find Entry to Restore`. +1. Select the file that contains the uncommitted changes. + ## Upload a new file To upload a new file in the Web IDE: @@ -203,7 +217,7 @@ To protect your privacy and data: - Carefully review the permissions requested by an extension before you install the extension. - Keep your extensions up to date to ensure that any security or privacy vulnerabilities are addressed promptly. --> -## Interactive web terminals for the Web IDE (Beta) +## Interactive web terminals for the Web IDE **(BETA)** WARNING: This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md deleted file mode 100644 index a4c733be376..00000000000 --- a/doc/user/project/web_ide_beta/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../web_ide/index.md' -remove_date: '2023-08-22' ---- - -This document was moved to [another location](../web_ide/index.md). - -<!-- This redirect file can be deleted after <2023-08-22>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 916c8abf066..ae182f1f183 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -26,7 +26,7 @@ can edit group wikis. Group wiki repositories can be moved using the To access a group wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. To display the wiki, either: - On the left sidebar, select **Plan > Wiki**. - On any page in the group, use the <kbd>g</kbd> + <kbd>w</kbd> @@ -66,7 +66,7 @@ can enable or disable a group wiki through the group settings. To open group settings: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 71fc4dd20a3..4f3aa0d0d49 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -31,7 +31,7 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se To access a project wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. To display the wiki, either: - On the left sidebar, select **Plan > Wiki**. - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> @@ -61,7 +61,7 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Select **Create your first page**. 1. GitLab requires this first page be titled `home`. The page with this @@ -77,7 +77,7 @@ to be used as your wiki's home page. To create it: Users with at least the Developer role can create new wiki pages: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. @@ -138,7 +138,7 @@ may not be able to check out the wiki locally afterward. You need at least the Developer role to edit a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to edit, and either: - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). @@ -157,7 +157,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the Developer role to delete a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to delete. 1. Select the edit icon (**{pencil}**). @@ -168,7 +168,7 @@ You need at least the Developer role to delete a wiki page: You need at least the Developer role to move a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). @@ -192,7 +192,7 @@ The history page shows: To view the changes for a wiki page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the page you want to view history for. 1. Select **Page history**. @@ -203,7 +203,7 @@ To view the changes for a wiki page: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. @@ -234,7 +234,7 @@ You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Plan > Wiki**. 1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -257,7 +257,7 @@ A `_sidebar` example, formatted with Markdown: Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) can enable or disable a project wiki by following the instructions in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +[Sharing and permissions](../settings/index.md#configure-project-features-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). @@ -268,7 +268,7 @@ You can disable group wikis from the [group settings](group.md#configure-group-w To add a link to an external wiki from a project's left sidebar: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. @@ -284,7 +284,7 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **External wiki**. 1. Under **Enable integration**, clear the **Active** checkbox. @@ -294,7 +294,7 @@ To hide the link to an external wiki: To disable a project's internal wiki: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 8c050caed17..2a4f0b99246 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -13,7 +13,7 @@ code are saved in projects, and most features are in the scope of projects. To view all projects for the GitLab instance: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Explore**. On the left sidebar, **Projects** is selected. On the right, the list shows @@ -25,7 +25,7 @@ If you are not authenticated, then the list shows public projects only. To view projects you are a member of: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. On the left sidebar, **Projects** is selected. On the list, on the **Yours** tab, @@ -68,7 +68,7 @@ Do not include sensitive information in the name of a topic. To explore project topics: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Explore**. 1. On the left sidebar, select **Topics**. 1. To view projects associated with a topic, select a topic. @@ -110,7 +110,7 @@ To subscribe to a topic: - From a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). @@ -132,25 +132,9 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. In the upper-right corner of the page, select **Star**. -## Delete a project - -After you delete a project: - -- Projects in personal namespaces are deleted immediately. -- Projects in groups are [deleted after a retention period](../project/settings/index.md#delayed-project-deletion). - -To delete a project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > General**. -1. Expand the **Advanced** section. -1. Scroll down to the **Delete project** section. -1. Select **Delete project**. -1. Confirm this action by completing the field. - ## View projects pending deletion **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. @@ -160,8 +144,8 @@ To delete a project: To view a list of all projects that are pending deletion: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. On the left sidebar, select **Search or go to**. +1. Select **View all my projects**. 1. Based on your GitLab version: - GitLab 14.6 and later: select the **Pending deletion** tab. - GitLab 14.5 and earlier: select the **Deleted projects** tab. @@ -176,7 +160,7 @@ Each project in the list shows: To view the activity of a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Activity**. 1. Optional. To filter activity by contribution type, select a tab: @@ -190,8 +174,8 @@ To view the activity of a project: ## Search in projects -To search through your projects, on the left sidebar, at the top, select **Search GitLab** -(**{search}**). GitLab filters as you type. +To search through your projects, on the left sidebar, select **Search or go to**. +GitLab filters as you type. You can also look for the projects you [starred](#star-a-project) (**Starred projects**). @@ -214,7 +198,7 @@ You can also choose to hide or show archived projects. You can filter projects by the programming language they use. To do this: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select either: - **View all your projects**, to filter your projects. - **Explore**, to filter all projects you can access. @@ -230,7 +214,7 @@ Prerequisite: - You must have the Owner role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggle by each feature you want to turn on or off, or change access for. @@ -274,7 +258,7 @@ When you leave a project: To leave a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a [group namespace](../namespace/index.md). @@ -408,18 +392,44 @@ To access the Geo secondary server with HTTP: The `go get` request generates HTTP traffic to the primary Geo server. When the module download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. +## Add a compliance framework to a project **(PREMIUM)** + +You can add compliance frameworks to projects in a group that has a [compliance framework](../group/compliance_frameworks.md). + +## Manage project access through LDAP groups + +You can [use LDAP to manage group membership](../group/access_and_permissions.md#manage-group-memberships-via-ldap). + +You cannot use LDAP groups to manage project access, but you can use the following workaround. + +Prerequisites: + +- You must [integrate LDAP with GitLab](../../administration/auth/ldap/index.md). +- You must be an administrator. + +1. [Create a group](../group/index.md#create-a-group) to track membership of your project. +1. [Set up LDAP synchronization](../../administration/auth/ldap/ldap_synchronization.md) for that group. +1. To use LDAP groups to manage access to a project, +[add the LDAP-synchronized group as a member](../group/manage.md) to the project. + ## Related topics - [Import a project](../../user/project/import/index.md). - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - [Fork a project](repository/forking_workflow.md#create-a-fork). -- [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-features-and-permissions). +- Adjust [project visibility](../../user/public_access.md#change-project-visibility) and [permissions](settings/index.md#configure-project-features-and-permissions). - [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) ## Troubleshooting When working with projects, you might encounter the following issues, or require alternate methods to complete specific tasks. +### `An error occurred while fetching commit data` + +When you visit a project, the message `An error occurred while fetching commit data` might be displayed +if you use an ad blocker in your browser. The solution is to disable your ad blocker +for the GitLab instance you are trying to access. + ### Find projects using an SQL query While in [a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), you can find and store an array of projects based on a SQL query: |
