diff options
Diffstat (limited to 'doc/user/project')
151 files changed, 1769 insertions, 1044 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 26708dece50..be47d6f18bd 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -130,8 +130,8 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Link**, enter the URL that the badges should point to. 1. Under **Badge image URL**, enter the URL of the image that should be displayed. @@ -151,8 +151,8 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter _Pipeline Status_. 1. Under **Link**, enter the following URL: @@ -180,8 +180,8 @@ If you need individual badges for each project, either: To add a new badge to a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under "Badge image URL" the URL of the image that should be displayed. @@ -202,8 +202,8 @@ Badges associated with a group can be edited or deleted only at the [group level You can view the exact link for your badges. Then you can use the link to embed the badge in your HTML or Markdown pages. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. @@ -269,8 +269,9 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge with a custom image to a group or project: -1. On the top bar, select **Main menu** and find your group or project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or + group. +1. Select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter the name for the badge. 1. Under **Link**, enter the URL that the badge should point to. diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index 7e622110291..0c12f7d476b 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -56,41 +56,56 @@ Changelog: feature ## Create a changelog -To generate changelog data based on commits in a repository, see +Changelogs are generated from the command line, using either the API or the +GitLab CLI. The changelog output is formatted in Markdown, and +[you can customize it](#customize-the-changelog-output). + +### From the API + +To generate changelogs via the API with a `curl` command, see [Add changelog data to a changelog file](../../api/repositories.md#add-changelog-data-to-a-changelog-file) in the API documentation. -The changelog output is formatted in Markdown, and [you can customize it](#customize-the-changelog-output). +### From the GitLab CLI -### Reverted commits +> [Introduced](https://gitlab.com/gitlab-org/cli/-/merge_requests/1222) in `glab` version 1.30.0. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. +Prerequisites: -To be treated as a revert commit, the commit message must contain the string -`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. +- You have installed and configured the [GitLab CLI](../../integration/glab/index.md), + version 1.30.0 or later. +- Your repository's tag naming schema matches + [the expected tag naming format](#customize-the-tag-format-when-extracting-versions). +- Commits include [changelog trailers](../../development/changelog.md). -When generating a changelog for a range, GitLab ignores commits both added and -reverted in that range. In this example, commit C reverts commit B. Because -commit C has no other trailer, only commit A is added to the changelog: +To generate the changelog: -```mermaid -graph LR - A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] - B --> C[Commit C<br>Reverts commit B] -``` +1. Update your local copy of your repository with `git fetch`. +1. To generate a changelog for the current version (as determined by `git describe --tags`) + with the default options: + - Run the command `glab changelog generate`. + - To save the output to a file, run the command `glab changelog generate > <filename>.md`. +1. To generate a changelog with customized options, run the command `glab changelog generate` + and append your desired options. Some options include: -However, if the revert commit (commit C) _also_ contains a changelog trailer, -both commits A and C are included in the changelog: - -```mermaid -graph LR - A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] - B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] -``` + - `--config-file [string]`: The path to the changelog configuration file in your project's + Git repository. Defaults to `.gitlab/changelog_config.yml`. + - Commit range: + - `--from [string]`: The start of the range of commits (as a SHA) to use for + generating the changelog. This commit itself isn't included in the changelog. + - `--to [string]`: The end of the range of commits (as a SHA) to use for + generating the changelog. This commit _is_ included in the list. Defaults to the `HEAD` + of the default project branch. + - `--date [string]`: The date and time of the release, in ISO 8601 (`2016-03-11T03:45:40Z`) + format. Defaults to the current time. + - `--trailer [string]`: The Git trailer to use for including commits. Defaults to `Changelog`. + - `--version [string]`: The version to generate the changelog for. -Commit B is skipped. +To learn more about the parameters available in GitLab CLI, run `glab changelog generate --help`. See the +[API documentation](../../api/repositories.md#add-changelog-data-to-a-changelog-file) +for definitions and usage. -### Customize the changelog output +## Customize the changelog output To customize the changelog output, edit the changelog configuration file. The default location for this configuration is `.gitlab/changelog_config.yml`. The file supports @@ -311,6 +326,34 @@ To test if your regular expression is working, you can use websites such as [regex101](https://regex101.com/). If the regular expression syntax is invalid, an error is produced when generating a changelog. +## Reverted commit handling + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. + +To be treated as a revert commit, the commit message must contain the string +`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. + +When generating a changelog for a range, GitLab ignores commits both added and +reverted in that range. In this example, commit C reverts commit B. Because +commit C has no other trailer, only commit A is added to the changelog: + +```mermaid +graph LR + A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B] +``` + +However, if the revert commit (commit C) _also_ contains a changelog trailer, +both commits A and C are included in the changelog: + +```mermaid +graph LR + A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] +``` + +Commit B is skipped. + ## Related topics - [Changelog-related endpoints](../../api/repositories.md) in the Repositories API diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 6c8edb8c3e5..87554e786ab 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -174,7 +174,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#gitlab-agent-for-kubernetes-supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -248,7 +248,10 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. In GitLab, on the top bar, select **Main menu > Admin > Settings > General** and expand the **Amazon EKS** section. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Amazon EKS**. 1. Check **Enable Amazon EKS integration**. 1. Enter your **Account ID**. 1. Enter your [access key and ID](#eks-access-key-and-id). diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 31d5a73757a..2ea7ac0f1fd 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -78,7 +78,7 @@ You can customize the deployment namespace in a few ways: - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, but the user is responsible for ensuring its existence. You can fully customize this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments-deprecated) + [`environment:kubernetes:namespace`](../../../ci/environments/configure_kubernetes_deployments.md) in `.gitlab-ci.yml`. When you customize the namespace, existing environments remain linked to their current diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 5ce1994ba36..ab6084acd5e 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -24,5 +24,5 @@ to a single project. To view project-level Kubernetes clusters: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Kubernetes clusters**. diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index e69dba6f977..272d59bd6a4 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -48,8 +48,8 @@ For example: To view the Code Owners of a file or directory: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Go to the file or directory you want to see the Code Owners for. 1. Optional. Select a branch or tag. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 13ee07097e1..5bd19fec0ba 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -56,14 +56,14 @@ As with all sensitive information, you should ensure only those who need access For human interactions, use credentials tied to users such as Personal Access Tokens. To help detect a potential secret leak, you can use the -[Audit Event](../../../administration/audit_event_streaming.md#example-payloads-for-ssh-events-with-deploy-key) feature. +[Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-ssh-events-with-deploy-key) feature. ## View deploy keys To view the deploy keys available to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Deploy keys**. The deploy keys available are listed: @@ -80,8 +80,8 @@ Prerequisites: - [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Complete the fields. 1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** @@ -101,8 +101,9 @@ Prerequisites: To create a public deploy key: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Deploy Keys**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Deploy Keys**. 1. Select **New deploy key**. 1. Complete the fields. - Use a meaningful description for **Name**. For example, include the name of the external host @@ -118,8 +119,8 @@ Prerequisites: To grant a public deploy key access to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Publicly accessible deploy keys**. 1. In the key's row, select **Enable**. @@ -138,8 +139,8 @@ Prerequisites: To disable a deploy key: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). @@ -160,7 +161,7 @@ There are a few scenarios where a deploy key fails to push to a - The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. -- **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#configure-a-protected-branch) of the protected branch. +- **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#add-protection-to-existing-branches) of the protected branch. All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index a81ccd043bd..0b9c42f2a60 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -92,10 +92,8 @@ Prerequisites: - You must have at least the Maintainer role for the project or group. -1. On the top bar, select **Main menu**, and: - - For a project deploy token, select **Projects** and find your project. - - For a group deploy token, select **Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. Complete the fields, and select the desired [scopes](#scope). 1. Select **Create deploy token**. @@ -113,10 +111,8 @@ Prerequisites: To revoke a deploy token: -1. On the top bar, select **Main menu**, and: - - For a project deploy token, select **Projects** and find your project. - - For a group deploy token, select **Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index f0ced95c8eb..11e538964a2 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -32,8 +32,8 @@ directory in your repository. To create an issue description template: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. 1. Next to the default branch, in the **File name** text box, enter `.gitlab/issue_templates/mytemplate.md`, @@ -52,8 +52,8 @@ that depend on the contents of commit messages and branch names. To create a merge request description template for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. 1. Next to the default branch, in the **File name** text box, enter `.gitlab/merge_request_templates/mytemplate.md`, @@ -118,14 +118,14 @@ that you can use when creating a new project in the instance. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. -With **group-level** description templates, you can store your templates in a single repository and -configure the group file templates setting to point to that repository. +With **group-level** description templates, you can select a repository within the group to store +your templates. Then, you can access these templates from other projects in the group. As a result, you can use the same templates in issues and merge requests in all the group's projects. To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Templates**. 1. From the dropdown list, select your template project as the template repository at group level. 1. Select **Save changes**. @@ -155,8 +155,8 @@ To set a default description template for merge requests, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > Merge requests**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > Merge requests**. 1. In the **Default description template for merge requests** section, fill in the text area. 1. Select **Save changes**. @@ -167,8 +167,8 @@ To set a default description template for issues, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and Ultimate: set the default template in project settings: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > General**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > General**. 1. Expand **Default description template for issues**. 1. Fill in the text area. 1. Select **Save changes**. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index c81ba4b7dd3..71b4bff41d1 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -219,8 +219,8 @@ To view the user who locked the file (if it was not you), hover over the button. To view and remove file locks: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Locked files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Locked files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index b523e007f0e..dc17a3646a8 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -70,8 +70,7 @@ For user contributions to be mapped, each user must complete the following befor > Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. 1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **Bitbucket Cloud**. 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 4d3a6eb87e0..fce9ca7d147 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -41,8 +41,7 @@ You can import Bitbucket repositories to GitLab. To import your Bitbucket repositories: 1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **Bitbucket Server**. 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 692ec1390d2..30c4249e0d6 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -29,8 +29,7 @@ users. To import your project from FogBugz: 1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **FogBugz**. 1. Enter your FogBugz URL, email address, and password. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index b2b1ede12d4..509029a3099 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -17,9 +17,11 @@ The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or `gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to different namespaces. -If you are importing to a self-managed GitLab instance, you can use the -[GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects -without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. +- If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. The + Rake task imports projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. +- If you are importing from GitHub Enterprise to GitLab.com, use the + [GitLab Import API](../../../api/import.md#import-repository-from-github) GitHub endpoint instead. This allows you to provide a different domain to import the project from. + Using the UI, the GitHub importer always imports from the `github.com` domain. When importing projects: @@ -30,6 +32,7 @@ When importing projects: - The importer also imports branches on forks of projects related to open pull requests. These branches are imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to a discrepancy in branches compared to those of the GitHub repository. +- The organization the repository belongs to must not impose restrictions of a [third-party application access policy](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) on the GitLab instance you import to. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview of the import process, see [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). @@ -137,11 +140,12 @@ Use one of the following tabs to filter the list of repositories: - **Collaborated**: Filter the list to the repositories that you have contributed to. - **Organization**: Filter the list to the repositories that belong to an organization you are a member of. -When the **Organization** tab is selected, you can further narrow down your search by selecting an available GitHub organization from a dropdown. +When the **Organization** tab is selected, you can further narrow down your search by selecting an available GitHub organization from a dropdown list. ### Select additional items to import -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5. +> - Importing collaborators as an additional item was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/398154) in GitLab 16.0. To make imports as fast as possible, the following items aren't imported from GitHub by default: @@ -183,17 +187,17 @@ To open an repository in GitLab URL after it has been imported, select its GitLa Completed imports can be re-imported by selecting **Re-import** and specifying new name. This creates a new copy of the source project. -![GitHub importer page](img/import_projects_from_github_importer_v12_3.png) +![GitHub importer page](img/import_projects_from_github_importer_v16_0.png) ### Check status of imports -> Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.0. +> Details of partially completed imports with a list of entities that failed to import [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386748) in GitLab 16.1. After imports are completed, they can be in one of three states: -- **Completed**: GitLab imported all repository entities. +- **Complete**: GitLab imported all repository entities. - **Partially completed**: GitLab failed to import some repository entities. -- **Failed**: GitLab imported no repository entities. +- **Failed**: GitLab aborted the import after a critical error occurred. Expand **Details** to see a list of [repository entities](#imported-data) that failed to import. @@ -280,12 +284,12 @@ When they are imported, supported GitHub branch protection rules are mapped to e | GitHub rule | GitLab rule | Introduced in | | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | -| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | -| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | +| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | +| **Require a pull request before merging** | **No one** option in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | | **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | | **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | | **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** | List of users in the **Allowed to push and merge** list of [branch protection settings](../protected_branches.md#add-protection-to-existing-branches) **(PREMIUM)**. Without a **Premium** subscription, the list of users that are allowed to push and merge is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue diff --git a/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png b/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png Binary files differdeleted file mode 100644 index 3ac03c0ecc5..00000000000 --- a/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/img/import_projects_from_github_importer_v16_0.png b/doc/user/project/import/img/import_projects_from_github_importer_v16_0.png Binary files differnew file mode 100644 index 00000000000..190474c4d89 --- /dev/null +++ b/doc/user/project/import/img/import_projects_from_github_importer_v16_0.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 1265b8534d0..9fdb8eed5aa 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -18,7 +18,7 @@ For any type of source and target, you can migrate GitLab projects: - When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in - [Beta](../../../policy/alpha-beta-support.md#beta). The feature is not ready for production use. + [Beta](../../../policy/experiment-beta-support.md#beta). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. @@ -26,7 +26,7 @@ If you only need to migrate Git repositories, you can [import each project by UR import issues and merge requests this way. To retain metadata like issues and merge requests, either: - [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). - This feature is in [Beta](../../../policy/alpha-beta-support.md#beta). It is not ready for production use. + This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -41,8 +41,9 @@ with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate gro GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. 1. Clear checkboxes for importers that are not required. @@ -113,8 +114,7 @@ You can view all project imports created by you. This list includes the followin To view project import history: 1. Sign in to GitLab. -1. On the top bar, select **Create new...** (**{plus-square}**). -1. Select **New project/repository**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 4ad51ccb97f..230113581f8 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -19,7 +19,8 @@ You can import your existing repositories by providing the Git URL. ## Import project by URL -1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 1512039fb25..67b96efe9a4 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -12,8 +12,7 @@ You can create a project in many ways in GitLab. To create a blank project: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. @@ -42,8 +41,7 @@ Anyone can [contribute a built-in template](../../development/project_templates. To create a project from a built-in template: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: @@ -73,8 +71,7 @@ Custom project templates are available at: - The [instance-level](../../user/admin_area/custom_project_templates.md) - The [group-level](../../user/group/custom_project_templates.md) -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: @@ -99,8 +96,7 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service To create a project from the HIPAA Audit Protocol template: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: @@ -138,7 +134,7 @@ Prerequisites: [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the top bar, select **Main menu > Groups** and find your group. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. In the upper-right corner, confirm that **New project** is visible. Contact your GitLab administrator if you require permission. diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 2874bf98736..5ca6fcebdd6 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -24,8 +24,8 @@ Prerequisites: To view project insights: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Insights**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Analyze > Insights**. 1. To view a report, select the **Select report** dropdown list. ## Configure project insights @@ -45,7 +45,7 @@ To configure project insights, either: - Create a `.gitlab/insights.yml` file locally in the root directory of your project, and push your changes. - Create a `.gitlab/insights.yml` file in the UI: - 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Above the file list, select the branch you want to commit to, select the plus icon, then select **New file**. 1. In the **File name** text box, enter `.gitlab/insights.yml`. 1. In the large text box, update the file contents. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 633d565064c..405531abd0d 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -29,14 +29,15 @@ An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.co GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: 1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. -1. Select **Apple App Store**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **Apple App Store Connect**. 1. Turn on the **Active** toggle under **Enable Integration**. 1. Provide the Apple App Store Connect configuration information: - **Issuer ID**: The Apple App Store Connect issuer ID. - **Key ID**: The key ID of the generated private key. - **Private Key**: The generated private key. You can download this key only once. + - **Protected branches and tags only**: Enable to only set variables on protected branches and tags. 1. Select **Save changes**. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index b1a4d2a2f78..edd08f1e3d3 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,13 +32,14 @@ In Asana, create a Personal Access Token. Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Asana. 1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. <!-- ## Troubleshooting --> diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 23990036f4e..8394687d8f5 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -36,8 +36,8 @@ integration in GitLab. ## Configure GitLab -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. 1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. @@ -47,8 +47,7 @@ integration in GitLab. 1. If necessary, enter a username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require authentication. -1. Optional. To test the configuration and trigger a build in Bamboo, - select **Test Settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. ### Identify the Bamboo build plan build key diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index f2af4dc6e4d..1796e674b00 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,8 +14,8 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: @@ -31,7 +31,8 @@ To enable the Bugzilla integration in a project: For example, for a project named "My Cool App": `https://bugzilla.example.org/enter_bug.cgi#h=dupes%7CMy+Cool+App`. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After you configure and enable Bugzilla, a link appears on the GitLab project pages. This link takes you to the appropriate Bugzilla project. diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md new file mode 100644 index 00000000000..bf2c738049c --- /dev/null +++ b/doc/user/project/integrations/clickup.md @@ -0,0 +1,54 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# ClickUp **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120732) in GitLab 16.1. + +You can use [ClickUp](https://clickup.com/) as an external issue tracker. +To enable the ClickUp integration in a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **ClickUp**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: + + - **Project URL**: The URL to the ClickUp project to link to this GitLab project. + - **Issue URL**: The URL to the ClickUp project issue to link to this GitLab project. + The URL must contain `:id`. GitLab replaces this ID with the issue number. + +1. Optional. Select **Test settings**. +1. Select **Save changes**. + +After you have configured and enabled ClickUp, you see the ClickUp link on the GitLab project pages, +which takes you to your ClickUp project. + +For example, this is a configuration for a project named `gitlab-ci`: + +- Project URL: `https://app.clickup.com/1234567` +- Issue URL: `https://app.clickup.com/t/:id` + +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). + +## Reference ClickUp issues in GitLab + +You can reference your ClickUp issues using: + +- `#<ID>`, where `<ID>` is a alphanumerical string (example `#8wrtcd932`). +- `CU-<ID>`, where `<ID>` is a alphanumerical string (example `CU-8wrtcd932`). +- `<PROJECT>-<ID>`, for example `API_32-143`, where: + - `<PROJECT>` is a ClickUp list custom prefix ID. + - `<ID>` is a number. + +In links, the `CU-` part is ignored and it links to the global URL of the issue. When a custom +prefix is used in a ClickUp list, the prefix part is part of the link. + +We suggest using the `CU-` format (`CU-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index b529d728e3b..9580c924fd1 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -20,8 +20,8 @@ on the left sidebar in your project. To enable a custom issue tracker in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 60b37f07bb5..180e39e3254 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -26,8 +26,8 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. 1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 7f8755f1114..eb3eecaa656 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -11,8 +11,8 @@ that is pushed to your project. To enable emails on push: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Emails on push**. 1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. 1. Configure the following options: diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 39dd548e7ca..d96558579d1 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,8 +14,8 @@ This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.n To enable the EWM integration, in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **EWM**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: @@ -35,7 +35,8 @@ To enable the EWM integration, in a project: Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem`. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Reference EWM work items in commit messages diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3e75106a9bc..98654a3b59f 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -29,8 +29,8 @@ Complete these steps on GitHub: Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **GitHub**. 1. Ensure the **Active** checkbox is selected. 1. In **Token**, paste the token you generated on GitHub. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index fabdf07f76f..8790c7213e5 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -107,8 +107,9 @@ With Slack notifications, GitLab can send messages to Slack workspace channels f To configure Slack notifications: -1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been [installed](#installation). -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for + which the GitLab for Slack app has been [installed](#installation). +1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. In the **Trigger** section, select the checkbox for each GitLab event you want to receive a notification for in Slack. For a full list, see @@ -162,8 +163,9 @@ New releases of the app might require permissions to be authorized before some f To update your GitLab for Slack app: -1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been configured. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for + which the GitLab for Slack app has been configured. +1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. Select **Reinstall GitLab for Slack app**. diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 2ae5a504e06..4b0f4fe205a 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -29,8 +29,8 @@ Prerequisites: To enable the Google Play integration in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Google Play**. 1. In **Enable integration**, select the **Active** checkbox. 1. In **Package name**, enter the package name of the app (for example, `com.gitlab.app_name`). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 3470d11b983..4046869072d 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -12,11 +12,11 @@ Hangouts). ## Integration workflow -To enable this integration, first you need to create a webhook for the room in +To enable this integration, you must first create a webhook for the space in Google Chat where you want to receive the notifications from your project. After that, enable the integration in GitLab and choose the events you want to -be notified about in your Google Chat room. +be notified about in your Google Chat space. For every selected event in your project, GitLab acts like a bot sending notifications to Google Chat: @@ -27,9 +27,9 @@ notifications to Google Chat: To enable the integration in Google Chat: -1. Enter the room where you want to receive notifications from GitLab. -1. In the upper-left corner, from the room dropdown list, select **Manage webhooks**. -1. Enter the name for your webhook, for example "GitLab integration". +1. Enter the space where you want to receive notifications from GitLab. +1. In the upper-left corner, from the space dropdown list, select **Apps and Integrations > Manage webhooks**. +1. Enter the name for your webhook (for example, `GitLab integration`). 1. Optional. Add an avatar for your bot. 1. Select **Save**. 1. Copy the webhook URL. @@ -40,6 +40,10 @@ For further details, see [the Google Chat documentation for configuring webhooks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27823) in GitLab 15.4. +WARNING: +In March 2023, Google [deprecated threaded replies in Google Chat](https://workspaceupdates.googleblog.com/2023/02/new-google-chat-spaces-will-be-in-line-threaded.html). +This feature does not work for new Google Chat spaces. You can still use this feature in existing Google Chat spaces where threaded replies are already enabled. + To enable threaded notifications for the same GitLab object (for example, an issue or merge request): 1. Go to [Google Chat](https://chat.google.com/). @@ -56,9 +60,9 @@ To enable the integration in GitLab: 1. In your project, go to **Settings > Integrations** and select **Google Chat**. 1. Scroll down to the end of the page where you find a **Webhook** field. 1. Enter the webhook URL you copied from Google Chat. -1. Select the events you want to be notified about in your Google Chat room. -1. Optional. Select **Test settings** to verify the connection. +1. Select the events you want to be notified about in your Google Chat space. +1. Optional. Select **Test settings**. 1. Select **Save changes**. To test the integration, make a change based on the events you selected and -see the notification in your Google Chat room. +see the notification in your Google Chat space. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 4a586054aee..12986cba555 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -25,8 +25,8 @@ In the Harbor instance, ensure that: GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Harbor**. 1. Turn on the **Active** toggle under **Enable Integration**. 1. Provide the Harbor configuration information: diff --git a/doc/user/project/integrations/img/merge_request_performance.png b/doc/user/project/integrations/img/merge_request_performance.png Binary files differdeleted file mode 100644 index a9cd761cdcb..00000000000 --- a/doc/user/project/integrations/img/merge_request_performance.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_dashboard.png b/doc/user/project/integrations/img/prometheus_dashboard.png Binary files differdeleted file mode 100644 index 24d855eb50c..00000000000 --- a/doc/user/project/integrations/img/prometheus_dashboard.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_manual_configuration_v13_2.png b/doc/user/project/integrations/img/prometheus_manual_configuration_v13_2.png Binary files differdeleted file mode 100644 index b6ec08f492d..00000000000 --- a/doc/user/project/integrations/img/prometheus_manual_configuration_v13_2.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index f7019b2eeb2..c70a58a24d2 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -18,8 +18,8 @@ Prerequisites: To view the available integrations for your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. You can also view and manage integration settings across [all projects in an instance or group](../../admin_area/settings/project_integration_management.md). For a single project, you can choose to inherit the instance or group configuration, @@ -50,6 +50,7 @@ You can configure the following integrations. | [Bugzilla](bugzilla.md) | Use Bugzilla as the issue tracker. | **{dotted-circle}** No | | Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | | Campfire | Connect to chat. | **{dotted-circle}** No | +| [ClickUp](clickup.md) | Use ClickUp as the issue tracker. | **{dotted-circle}** No | | [Confluence Workspace](../../../api/integrations.md#confluence-integration) | Use Confluence Cloud Workspace as an internal wiki. | **{dotted-circle}** No | | [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | | [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | **{check-circle}** Yes | @@ -80,6 +81,7 @@ You can configure the following integrations. | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | | [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes | +| [Telegram](telegram.md) | Send notifications about project events to Telegram. | **{dotted-circle}** No | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index df11ed3e57c..7d3c85b2c62 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,8 +39,8 @@ network. For more details, read ## Complete these steps in GitLab -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. 1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty, @@ -50,8 +50,9 @@ network. For more details, read It's prepended to every channel or user provided under **Recipients**, which is not a full URI. 1. Under **Recipients**, enter the users or channels to receive updates, separated by spaces (for example, `#channel1 user1`). For more details, see [Enter irker recipients](#enter-irker-recipients). -1. Optional. Under **Colorize messages**, select the checkbox. irker will highlight your messages. -1. Select **Save changes** or optionally select **Test Settings**. +1. Optional. To highlight messages, select the **Colorize messages** checkbox. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Enter irker recipients diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index a50d341c38e..a73c0f001f3 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -41,8 +41,8 @@ Display name override is not enabled by default, you need to ask your administra After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Mattermost notifications**. 1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel to receive the notification. You do not need to add the hash sign (`#`). diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 3b5e4030487..a8d8323a651 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -17,9 +17,9 @@ separately configured [Mattermost notifications](mattermost.md). GitLab provides different ways to configure Mattermost slash commands. For any of these options, you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/). -- **Omnibus GitLab installations**: Mattermost is bundled with - [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, - read the [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). +- **Linux package installations**: Mattermost is bundled with + [Linux package](https://docs.gitlab.com/omnibus/). To configure Mattermost for Linux package + installations, read the [Linux package Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the [automated configuration](#configure-automatically). - **For all other installations**, use the [manual configuration](#configure-manually). @@ -29,9 +29,9 @@ you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/pla If Mattermost is installed on the same server as GitLab, you can automatically configure Mattermost slash commands: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **Mattermost slash commands**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **Mattermost slash commands**. 1. In **Enable integration**, ensure the **Active** checkbox is selected. 1. Select **Add to Mattermost**, and select **Save changes**. @@ -65,8 +65,9 @@ To get configuration values from GitLab: 1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. 1. Copy the **Request URL** value. All other values are suggestions. 1. Do not close this browser tab. You need it in a later step. @@ -133,7 +134,7 @@ The available slash commands for Mattermost are: ## Related topics - [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) -- [Omnibus GitLab Mattermost](../../../integration/mattermost/index.md) +- [Linux package Mattermost](../../../integration/mattermost/index.md) ## Troubleshooting diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 5d2c27fc2a4..3d0b77069a3 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -35,8 +35,8 @@ After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Microsoft Teams notifications**. 1. To enable the integration, select **Active**. 1. In the **Trigger** section, select the checkbox next to each event to enable it: diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index 75fae4647d0..cffa2649cc8 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -6,10 +6,10 @@ info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering pr # MLflow client integration **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. NOTE: -Model experiment tracking is an [experimental feature](../../../policy/alpha-beta-support.md). +Model experiment tracking is an [experimental feature](../../../policy/experiment-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. [MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. @@ -23,7 +23,9 @@ GitLab plays the role of a MLflow server. Running `mlflow server` is not necessa Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) for the project, with minimum access level of `api`. -- The project ID. To find the project ID, on the top bar, select **Main menu > Projects** and find your project. On the left sidebar, select **Settings > General**. +- The project ID. To find the project ID: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > General**. To enable MLflow client integration: diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index e1d48037ba8..7f53f08e808 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,11 +37,12 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar Complete these steps in GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Pivotal Tracker. 1. Optional. To restrict this setting to specific branches, list them in the **Restrict to branch** field, separated with commas. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index e05ff9489ca..62703ebfad9 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -26,14 +26,15 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. 1. To enable the integration for your instance: - 1. On the top bar, select **Main menu > Admin**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Pumble. 1. Paste the **Webhook** URL for the Pumble channel. 1. Configure the remaining options. -1. Optional. To test the integration, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. The Pumble channel begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index df8a6681e2b..9cb93c2d082 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -9,8 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Redmine**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: @@ -24,7 +24,8 @@ To enable the Redmine integration in a project: **This URL is not used and removal is planned in a future release.** For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages, which takes you to your Redmine project. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index cf9745929a1..6fbd246d7f4 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -21,11 +21,11 @@ This change is a breaking change. ## Configure settings in GitLab -To enable the Shimo integration for your group or project: +To enable the Shimo integration for your project: -1. On the top bar, select **Main menu** and find your group or project. -1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **Shimo**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **Shimo**. 1. In **Enable integration**, ensure the **Active** checkbox is selected. 1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). 1. Select **Save changes**. @@ -36,8 +36,8 @@ On the left sidebar, **Shimo** now appears instead of **Wiki**. To view the Shimo Workspace from your group or project: -1. On the top bar, select **Main menu** and find your group or project. -1. On the left sidebar, select **Shimo**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. <!--- end_remove --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5b769b84663..14183a47625 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -32,8 +32,8 @@ to control GitLab from Slack. Slash commands are configured separately. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab @@ -56,8 +56,8 @@ to control GitLab from Slack. Slash commands are configured separately. 1. Leave the **Labels to be notified** field blank to get all notifications, or add labels that the issue or merge request must have to trigger a notification. -1. Select **Test settings** to verify your information, and then select - **Save changes**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 4fa4b75422e..74bd12561fb 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -19,11 +19,10 @@ The [Slack notifications integration](slack.md) is configured separately. ## Configure GitLab and Slack -Slack slash command integrations -are scoped to a project. +Slack slash command integrations are scoped to a project. -1. In GitLab, on the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Slack slash commands**. Leave this browser tab open. 1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). 1. Enter a trigger command. We suggest you use the project name. diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index 2a1106edb0c..ff633783e83 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -26,8 +26,8 @@ are synchronized as requirements in Squash TM and test progress is reported in G ## Configure GitLab -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Squash TM**. 1. Ensure that the **Active** toggle is enabled. 1. In the **Trigger** section, indicate which type of issue is concerned by the real-time synchronization. diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md new file mode 100644 index 00000000000..9d36a16f5fc --- /dev/null +++ b/doc/user/project/integrations/telegram.md @@ -0,0 +1,57 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Telegram **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122879) in GitLab 16.1. + +You can configure GitLab to send notifications to a Telegram chat or channel. +To set up the Telegram integration, you must: + +1. [Create a Telegram bot](#create-a-telegram-bot). +1. [Configure the Telegram bot](#configure-the-telegram-bot). +1. [Set up the Telegram integration in GitLab](#set-up-the-telegram-integration-in-gitlab). + +## Create a Telegram bot + +To create a bot in Telegram: + +1. Start a new chat with `@BotFather`. +1. [Create a new bot](https://core.telegram.org/bots/features#creating-a-new-bot) as described in the Telegram documentation. + +When you create a bot, `BotFather` provides you with an API token. Keep this token secure as you need it to authenticate the bot in Telegram. + +## Configure the Telegram bot + +To configure the bot in Telegram: + +1. Add the bot as an administrator to a new or existing channel. +1. Assign the bot `Post Messages` rights to receive events. +1. Create an identifier for the channel. + - For public channels, enter a public link and copy the channel identifier (for example, `https:/t.me/MY_IDENTIFIER`). + - For private channels, use the [`getUpdates`](https://telegram-bot-sdk.readme.io/reference/getupdates) method with your API token and copy the channel identifier. + +## Set up the Telegram integration in GitLab + +After you invite the bot to a Telegram channel, you can configure GitLab to send notifications: + +1. To enable the integration: + - **For your group or project:** + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. Select **Settings > Integrations**. + - **For your instance:** + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Settings > Integrations**. +1. Select **Telegram**. +1. In **Enable integration**, select the **Active** checkbox. +1. In **New token**, [paste the token value from the Telegram bot](#create-a-telegram-bot). +1. In the **Trigger** section, select the checkboxes for the GitLab events you want to receive in Telegram. +1. In **Channel identifier**, [paste the Telegram channel identifier](#configure-the-telegram-bot). +1. Optional. Select **Test settings**. +1. Select **Save changes**. + +The Telegram channel can now receive all selected GitLab events. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index d20b19a3aaa..7d0dd6d2af3 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,14 +15,15 @@ copy its URL. In GitLab: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. 1. In the **Branches for which notifications are to be sent** dropdown list, select which types of branches to send notifications for. -1. Select `Save changes` or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. Your Unify Circuit conversation now starts receiving GitLab event notifications. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index c755c7a5c17..3ba05476e63 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -21,18 +21,22 @@ You can configure GitLab to send notifications to a Webex Teams space: ## Configure settings in GitLab -Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send +After you have a webhook URL for your Webex Teams space, you can configure GitLab to send notifications: -1. Navigate to: - - **Settings > Integrations** in a project to enable the integration at the project level. - - **Settings > Integrations** in a group to enable the integration at the group level. - - On the top bar, select **Main menu > Admin**. Then, in the left sidebar, - select **Settings > Integrations** to enable an instance-level integration. +1. To enable integration: + - At the project or group level: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. + 1. Select **Settings > Integrations**. + - At the instance level: + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **Settings > Integrations**. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. 1. Paste the **Webhook** URL for the Webex Teams space. -1. Configure the remaining options and then select **Test settings and save changes**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. The Webex Teams space begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index fda778aa167..dfff537e4a1 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -786,7 +786,7 @@ Payload example: "noteable_id": 53, "system": false, "st_diff": null, - "url": "http://example.com/gitlab-org/gitlab-test/snippets/53#note_1245" + "url": "http://example.com/gitlab-org/gitlab-test/-/snippets/53#note_1245" }, "snippet": { "id": 53, @@ -799,7 +799,8 @@ Payload example: "file_name": "test.rb", "expires_at": null, "type": "ProjectSnippet", - "visibility_level": 0 + "visibility_level": 0, + "url": "http://example.com/gitlab-org/gitlab-test/-/snippets/53" } } ``` @@ -1109,6 +1110,9 @@ and later, the pipeline webhook returns only the latest jobs. In [GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89546) and later, pipeline webhooks triggered by blocked users are not processed. +In [GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123639) +and later, pipeline webhooks started to expose `object_attributes.name`. + Request header: ```plaintext @@ -1123,6 +1127,7 @@ Payload example: "object_attributes":{ "id": 31, "iid": 3, + "name": "Pipeline for branch: master", "ref": "master", "tag": false, "sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", @@ -1142,7 +1147,8 @@ Payload example: "key": "NESTOR_PROD_ENVIRONMENT", "value": "us-west-1" } - ] + ], + "url": "http://example.com/gitlab-org/gitlab-test/-/pipelines/31" }, "merge_request": { "id": 1, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 7fcb2680504..5c8fc5703dd 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -136,10 +136,25 @@ intermittently and are temporarily disabled. These webhooks are initially disabl for one minute, which is extended on each subsequent failure up to a maximum of 24 hours. Project or group webhooks that return response codes in the `4xx` range are understood to be -misconfigured and are permanently disabled until you manually re-enable -them yourself. +misconfigured and are permanently disabled until you [manually re-enable](#re-enable-disabled-webhooks) +the webhooks yourself. -For more information about disabled webhooks, see [troubleshooting](#troubleshooting). +### Re-enable disabled webhooks + +> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. + +If a webhook is failing, a banner displays at the top of the edit page explaining +why the webhook is disabled and when it is automatically re-enabled. For example: + +![A banner for a failing webhook, warning it has failed to connect and is retrying in 60 minutes](img/failed_banner.png) + +In the case of a failed webhook, an error banner is displayed: + +![A banner for a failed webhook, showing an error state, and explaining how to re-enable it](img/failed_banner_error.png) + +To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test +request succeeds, the webhook is re-enabled. ## Test a webhook @@ -274,6 +289,33 @@ Webhook requests to your endpoint include the following headers: | `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | +## Develop webhooks + +If you don't have an existing HTTPS endpoint or URL for your webhook setup, you must deploy one on a server. This HTTPS endpoint is used in configuration. To develop against GitLab webhooks and capture the payloads, you can use: + +- [Public webhook inspection and testing tools](#public-webhook-inspection-and-testing-tools) +- [The GitLab Development Kit (GDK)](#gitlab-development-kit-gdk) +- [Recently triggered webhook payloads in GitLab settings](#recently-triggered-webhook-payloads-in-gitlab-settings) + +### Public webhook inspection and testing tools + +You can use public tools to inspect and test webhook payloads. These tools act as catch-all endpoints for HTTP requests and respond with a `200 OK` HTTP status code. You can use these payloads to develop your webhook services. + +You should exercise caution when using these tools as you might be sending sensitive data to external tools. You should use test tokens with these tools and rotate any secrets inadvertently sent to a third party. + +These public tools include: + +- [Beeceptor](https://beeceptor.com) to create a temporary HTTPS endpoint and inspect incoming payloads +- [Webhook.site](https://webhook.site) to review incoming payloads + +### GitLab Development Kit (GDK) + +For a safer development environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit) to develop against GitLab webhooks locally. With the GDK, you can send webhooks from your local GitLab instance to a webhook receiver running locally on your machine. To use this approach, you must install and configure the GDK. + +### Recently triggered webhook payloads in GitLab settings + +You can [review recently triggered webhook payloads](#troubleshooting) in GitLab settings. For each webhook event, a detail page exists with information about the data GitLab sends and receives from the webhook endpoint. + ## Troubleshooting > **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3. @@ -334,19 +376,4 @@ If you're receiving multiple webhook requests, the webhook might have timed out. GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout). -### Re-enable disabled webhooks - -> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. - -If a webhook is failing, a banner displays at the top of the edit page explaining -why it is disabled, and when it is automatically re-enabled. For example: - -![A banner for a failing webhook, warning it has failed to connect and is retrying in 60 minutes](img/failed_banner.png) - -In the case of a failed webhook, an error banner is displayed: - -![A banner for a failed webhook, showing an error state, and explaining how to re-enable it](img/failed_banner_error.png) - -To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test -request succeeds, the webhook is re-enabled. +If a webhook is not triggered, the webhook might be [automatically disabled](#failing-webhooks). diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index ee5ca8eca78..8845aa8fdfd 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,15 +14,16 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **YouTrack**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: - **Project URL**: The URL to the project in YouTrack. - **Issue URL**: The URL to view an issue in the YouTrack project. The URL must contain `:id`. GitLab replaces `:id` with the issue number. -1. Select **Save changes** or optionally select **Test settings**. +1. Optional. Select **Test settings**. +1. Select **Save changes**. After you configure and enable YouTrack, a link appears on the GitLab project pages. This link takes you to the appropriate YouTrack project. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 19f6a3e315c..b14b9eac9da 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -52,7 +52,7 @@ Complete these steps in GitLab: ![ZenTao settings page](img/zentao_product_id.png) -1. To verify the ZenTao connection is working, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. <!--- end_remove --> diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 79278d1b3ad..7e5f26d3526 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -15,36 +15,36 @@ keep security vulnerabilities private or prevent surprises from leaking out. You can make an issue confidential when you create or edit an issue. +### In a new issue + When you create a new issue, a checkbox right below the text area is available to mark the issue as confidential. Check that box and select **Create issue** -to create the issue. For existing issues, edit them, check the -confidential checkbox and select **Save changes**. +to create the issue. When you create a confidential issue in a project, the project becomes listed in the **Contributed projects** section in your [profile](../../profile/index.md). **Contributed projects** does not show information about the confidential issue; it only shows the project name. -![Creating a new confidential issue](img/confidential_issues_create_v15_4.png) - -## Modify issue confidentiality +To create a confidential issue: -There are two ways to change an issue's confidentiality. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, at the top, select **Create new...** (**{plus}**). +1. From the dropdown list, select **New issue**. +1. Complete the [fields](create_issues.md#fields-in-the-new-issue-form). + - Select the **This issue is confidential...** checkbox. +1. Select **Create issue**. -The first way is to edit the issue and toggle the confidentiality checkbox. -After you save the issue, the confidentiality of the issue is updated. +### In an existing issue -The second way is to locate the **Confidentiality** section in the sidebar and select -**Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. +To change the confidentiality of an existing issue: -| Turn off confidentiality | Turn on confidentiality | -| :-----------: | :----------: | -| ![Turn off confidentiality](img/turn_off_confidentiality_v15_1.png) | ![Turn on confidentiality](img/turn_on_confidentiality_v15_1.png) | - -Every change from regular to confidential and vice versa, is indicated by a -system note in the issue's comments: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. +1. Select the title of your issue to view it. +1. On the right sidebar, next to **Confidentiality**, select **Edit**. +1. Select **Turn on** (or **Turn off** to make the issue non-confidential). -![Confidential issues system notes](img/confidential_issues_system_notes_v15_4.png) +Alternatively, you can use the `/confidential` [quick action](../quick_actions.md#issues-merge-requests-and-epics). -- **{eye-slash}** The issue is made confidential. -- **{eye}** The issue is made public. +## Who can see confidential issues When an issue is made confidential, only users with at least the Reporter role for the project have access to the issue. @@ -53,8 +53,8 @@ the issue even if they were actively participating before the change. ## Confidential issue indicators -There are a few things that visually separate a confidential issue from a -regular one. In the issues index page view, you can see the confidential (**{eye-slash}**) icon +Confidential issues are visually different from regular issues in a few ways. +In the issues index page view, you can see the confidential (**{eye-slash}**) icon next to the issues that are marked as confidential: ![Confidential issues index page](img/confidential_issues_index_page.png) @@ -62,8 +62,6 @@ next to the issues that are marked as confidential: If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), you cannot see confidential issues at all. ---- - Likewise, while inside the issue, you can see the confidential (**{eye-slash}**) icon right next to the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential. @@ -76,6 +74,14 @@ There is also an indicator on the sidebar denoting confidentiality. | :-----------: | :----------: | | ![Sidebar confidential issue](img/sidebar_confidential_issue.png) | ![Sidebar not confidential issue](img/sidebar_not_confidential_issue.png) | +Every change from regular to confidential and vice versa, is indicated by a +system note in the issue's comments: + +- **{eye-slash}** The issue is made confidential. +- **{eye}** The issue is made public. + +![Confidential issues system notes](img/confidential_issues_system_notes_v15_4.png) + ## Merge requests for confidential issues Although you can create confidential issues (and make existing issues confidential) in a public project, you cannot make confidential merge requests. @@ -83,7 +89,7 @@ Learn how to create [merge requests for confidential issues](../merge_requests/c ## Permissions and access to confidential issues -There are two kinds of level access for confidential issues. The general rule +Access to confidential issues is by one of two routes. The general rule is that confidential issues are visible only to members of a project with at least the **Reporter role**. diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 4511c89b0ff..3e7cfc12da7 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -28,11 +28,11 @@ Prerequisites: To create an issue: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Either: - - On the left sidebar, select **Issues**, and then, in the upper-right corner, select **New issue**. - - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, + - On the left sidebar, select **Plan > Issues**, and then, in the upper-right corner, select **New issue**. + - On the left sidebar, at the top, select the plus sign (**{plus}**) and then, under **In this project**, select **New issue**. 1. Complete the [fields](#fields-in-the-new-issue-form). @@ -51,8 +51,8 @@ Prerequisites: To create an issue from a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Issues**. 1. In the upper-right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. @@ -98,7 +98,7 @@ Prerequisites: To create an issue from a project issue board: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Issues > Boards**. 1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. @@ -106,7 +106,7 @@ To create an issue from a project issue board: To create an issue from a group issue board: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Issues > Boards**. 1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. @@ -130,8 +130,8 @@ Prerequisites: To email an issue to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. Select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. At the bottom of the page, select **Email a new issue to this project**. 1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). 1. From your email client, send an email to this address. @@ -197,7 +197,7 @@ To offer email support, enable [Service Desk](../service_desk.md) for your proje Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there. -### Fields in the new issue form +## Fields in the new issue form > - Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. > - Iteration field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233517) in GitLab 15.6. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 10b29feb072..9c04a40cb32 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -70,7 +70,7 @@ Support for PDF files is tracked in [issue 32811](https://gitlab.com/gitlab-org/ - [A project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429). - [An issue is deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427). - In GitLab 12.7 and later, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) - by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). + and in GitLab 16.1 and later it can be [verified by Geo as well](https://gitlab.com/gitlab-org/gitlab/-/issues/355660). ## View a design @@ -119,9 +119,7 @@ To move around the image while zoomed in, drag the image. ## Add a design to an issue -> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. -> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. -> - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. +> Ability to edit the description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1. Prerequisites: @@ -199,6 +197,21 @@ Only the latest version of the designs can be archived. Archived designs are not permanently lost. You can browse [previous versions](#add-a-new-version-of-a-design). +<!-- When content_editor_on_issues flag is removed, move version notes + to "Add a design to an issue", update that topic, and delete the one below. --> + +## Markdown and rich text editors for descriptions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +When this feature is enabled, you can use the Markdown and rich text editor in design descriptions. +It's the same editor you use for comments across GitLab. + ## Reorder designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. diff --git a/doc/user/project/issues/img/confidential_issues_create_v15_4.png b/doc/user/project/issues/img/confidential_issues_create_v15_4.png Binary files differdeleted file mode 100644 index ff489ad8605..00000000000 --- a/doc/user/project/issues/img/confidential_issues_create_v15_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png b/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png Binary files differdeleted file mode 100644 index e6050aec0de..00000000000 --- a/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png +++ /dev/null diff --git a/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png b/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png Binary files differdeleted file mode 100644 index c81ac85ab13..00000000000 --- a/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 6c9a645d817..a43dd65ed74 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -22,6 +22,13 @@ For more information about using issues, see the GitLab blog post: Issues are always associated with a specific project. If you have multiple projects in a group, you can view all of the projects' issues at once. +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=tTE6omrBBZI">Issues - Setting up your Organization with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/tTE6omrBBZI" frameborder="0" allowfullscreen> </iframe> +</figure> + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> To learn how the GitLab Strategic Marketing department uses GitLab issues with [labels](../labels.md) and [issue boards](../issue_board.md), see the video on diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 276cc3bc7a5..6f1c14b2b80 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -18,6 +18,8 @@ Prerequisites: To edit an issue: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select the title of your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the available fields. 1. Select **Save changes**. @@ -52,8 +54,8 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. 1. From the sidebar, edit the available fields. @@ -85,8 +87,8 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. 1. From the sidebar, edit the available fields. @@ -114,7 +116,8 @@ Prerequisites: To move an issue: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, select **Move issue**. 1. Search for a project to move the issue to. 1. Select **Move**. @@ -125,7 +128,7 @@ To move an issue: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15991) in GitLab 15.6. -You can move multiple issues at the same time when you’re in a project. +You can move multiple issues at the same time when you're in a project. You can't move tasks or test cases. Prerequisite: @@ -134,8 +137,8 @@ Prerequisite: To move multiple issues at the same time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. Select **Bulk edit**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to move. 1. From the right sidebar, select **Move selected**. @@ -204,10 +207,13 @@ Prerequisites: - You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. -To close an issue, you can do the following: +To close an issue, you can either: -- At the top of the issue, select **Close issue**. - In an [issue board](../issue_board.md), drag an issue card from its list into the **Closed** list. +- From any other page in the GitLab UI: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Plan > Issues**, then select your issue to view it. + 1. At the top of the issue, select **Close issue**. <!-- Delete when the `moved_mr_sidebar` feature flag is removed --> If you don't see this action at the top of an issue, your project or instance might have @@ -300,8 +306,8 @@ Prerequisites: To disable automatic issue closing: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Branch defaults**. 1. Clear the **Auto-close referenced issues on default branch** checkbox. 1. Select **Save changes**. @@ -330,6 +336,8 @@ Prerequisites: To change issue type: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. To the right of the title, select **Edit title and description** (**{pencil}**). 1. Edit the issue and select an issue type from the **Issue type** dropdown list: @@ -348,12 +356,16 @@ Prerequisites: To delete an issue: -1. In an issue, select **Issue actions** (**{ellipsis_v}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Delete issue**. Alternatively: -1. In an issue, select **Edit title and description** (**{pencil}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select the title of your issue to view it. +1. Select **Edit title and description** (**{pencil}**). 1. Select **Delete issue**. ## Promote an issue to an epic **(PREMIUM)** @@ -366,7 +378,9 @@ You can promote an issue to an [epic](../../group/epics/index.md) in the immedia To promote an issue to an epic: -1. In an issue, select **Issue actions** (**{ellipsis_v}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. On the top right corner, select **Issue actions** (**{ellipsis_v}**). 1. Select **Promote to epic**. Alternatively, you can use the `/promote` [quick action](../quick_actions.md#issues-merge-requests-and-epics). @@ -387,7 +401,8 @@ You can use the `/promote_to_incident` [quick action](../quick_actions.md) to pr To add an issue to an [iteration](../../group/iterations/index.md): -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Iteration** section, select **Edit**. 1. From the dropdown list, select the iteration to associate this issue with. 1. Select any area outside the dropdown list. @@ -398,13 +413,13 @@ Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#i To view all issues assigned to you: -1. On the top bar, put your cursor in the **Search** box. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). 1. From the dropdown list, select **Issues assigned to me**. Or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>. -- On the top bar, in the upper-right corner, select **Issues** (**{issues}**). +- On the left sidebar, at the top, select **Issues** (**{issues}**). ## Filter the list of issues @@ -417,6 +432,8 @@ Or: To filter the list of issues: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. Above the list of issues, select **Search or filter results...**. 1. In the dropdown list that appears, select the attribute you want to filter by. 1. Select or type the operator to use for filtering the attribute. The following operators are @@ -456,8 +473,8 @@ when you [filter the list of issues](#filter-the-list-of-issues) by: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > List**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**. 1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. ![filter issues by specific ID](img/issue_search_by_id_v15_0.png) @@ -469,7 +486,8 @@ To refer to an issue elsewhere in GitLab, you can use its full URL or a short re To copy the issue reference to your clipboard: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, next to **Reference**, select **Copy Reference** (**{copy-to-clipboard}**). You can now paste the reference into another description or comment. @@ -492,7 +510,8 @@ For more information about creating comments by sending an email and the necessa To copy the issue's email address: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). ## Assignee @@ -508,7 +527,8 @@ themselves or another project member assigns them. To change the assignee on an issue: -1. Go to your issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Assignee** section, select **Edit**. 1. From the dropdown list, select the user to add as an assignee. 1. Select any area outside the dropdown list. @@ -548,7 +568,8 @@ Prerequisites: To edit health status of an issue: -1. Go to the issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. On the right sidebar, in the **Health status** section, select **Edit**. 1. From the dropdown list, select the status to add to this issue: @@ -556,7 +577,7 @@ To edit health status of an issue: - Needs attention (amber) - At risk (red) -You can see the issue’s health status in: +You can see the issue's health status in: - Issues list - Epic tree diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 2af15e06b98..7f98b62cabf 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -69,8 +69,8 @@ You can also assign and unassign labels with [quick actions](quick_actions.md): To view the **project's labels**: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. Or: @@ -86,8 +86,8 @@ project or group path where it was created. To view the **group's labels**: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. Or: @@ -108,8 +108,8 @@ Prerequisites: To create a project label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). @@ -142,8 +142,8 @@ To do so: To create a group label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). @@ -182,16 +182,16 @@ Prerequisites: To edit a **project** label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). ### Edit a group label To edit a **group** label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). ## Delete a label @@ -208,8 +208,8 @@ Prerequisites: To delete a **project** label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Either: - Next to the **Subscribe** button, select (**{ellipsis_v}**). @@ -221,8 +221,8 @@ To delete a **project** label: To delete a **group** label: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Group information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Labels**. 1. Either: - Next to the **Subscribe** button, select (**{ellipsis_v}**). @@ -251,8 +251,8 @@ Prerequisites: To promote a project label to a group label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. @@ -302,8 +302,8 @@ Prerequisites: To add the default labels to the project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Select **Generate a default set of labels**. The following labels are created: @@ -441,8 +441,8 @@ Prerequisites: To prioritize a label: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Labels**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Labels**. 1. Next to a label you want to prioritize, select the star (**{star-o}**). ![Labels prioritized](img/labels_prioritized_v13_5.png) diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8b2cacf084e..7a1d9d6e6e3 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -118,8 +118,8 @@ Prerequisite: To add a user to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Invite members**. 1. If the user: @@ -176,8 +176,8 @@ Prerequisites: To add a group to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Invite a group**. 1. Select a group. 1. Select the highest [role](../../permissions.md) for users in the group. @@ -207,8 +207,8 @@ If the importing member's role in the target project is: To import users: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. @@ -232,8 +232,8 @@ Prerequisites: To remove a member from a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Next to the project member you want to remove, select **Remove member**. 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. @@ -269,8 +269,8 @@ You can filter and sort members in a project. ### Display inherited members -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. @@ -278,8 +278,8 @@ You can filter and sort members in a project. ### Display direct members -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press <kbd>Enter</kbd>. @@ -301,8 +301,8 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. On the top bar, select **Main menu > Projects** and find the project you want to be a member of. -1. By the project name, select **Request Access**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to be a member of. +1. By the project's name, select **Request Access**. ![Request access button](img/request_access_button.png) @@ -325,8 +325,8 @@ Prerequisite: - You must be the project owner. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. 1. Select **Save changes**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 452363c3d9a..aadc27fb2d3 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -57,16 +57,21 @@ You can share a project with a group by inviting that group to the project. To invite a group to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. Select **Invite a group**. 1. **Select a group** you want to add to the project. 1. **Select a role** you want to assign to the group. 1. Optional. Select an **Access expiration date**. 1. Select **Invite**. -All group members, members of subgroups, and members of other projects the group has access to -are given access to the project. In addition: +The following members are given access to the project: + +- All direct group members. +- Inherited group members. +- Members of other groups that have access to the group being invited (by [group share](../../group/manage.md#share-a-group-with-another-group)) + +In addition: - On the group's page, the project is listed on the **Shared projects** tab. - On the project's **Members** page, the group is listed on the **Groups** tab. @@ -93,8 +98,8 @@ For example, if a group member has the role of Developer, and the group is invit To view the maximum role assigned to a member: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Members**. 1. In the **Max role** column, view the user's maximum assigned role. ## View a group's shared projects @@ -103,7 +108,7 @@ In a group, a shared project is a project to which the group members gained acce To view a group's shared projects: -1. On the top bar, select **Main menu > Group** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. On the group page, select the **Shared projects** tab. A list of shared projects is displayed. diff --git a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_16_0.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_16_0.png Binary files differnew file mode 100644 index 00000000000..727dac0916b --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_16_0.png diff --git a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png Binary files differdeleted file mode 100644 index 306bf57354d..00000000000 --- a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png +++ /dev/null diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 717358df9f3..68d5665139a 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -67,7 +67,7 @@ if a user approves a merge request and is shown in the reviewer list, a green ch After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, -such as merge conflicts, [unresolved threads](../../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved), +such as merge conflicts, [unresolved threads](../index.md#prevent-merge-unless-all-threads-are-resolved), or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). To prevent merge request authors from approving their own merge requests, @@ -109,11 +109,11 @@ Without the approvals, the work cannot merge. Required approvals enable multiple > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default. +> - [Enabled by default on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/405023) in GitLab 16.1. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, -ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. -On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Whenever an approval rule cannot be satisfied, the rule is displayed as **(!) Auto approved**. This applies to the following conditions: diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index d55ca5dff04..bc5d4353ffc 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -104,7 +104,7 @@ supports multiple default rules: When an [eligible approver](#eligible-approvers) approves a merge request, it reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: -![Approvals premium merge request widget](img/approvals_premium_mr_widget_v13_3.png) +![Approvals premium merge request widget](img/approvals_premium_mr_widget_16_0.png) <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Multiple Approvers](https://www.youtube.com/watch?v=8JQJ5821FrA). @@ -186,8 +186,8 @@ oversight on proposed work. To enable approval permissions for these users witho granting them push access: 1. [Create a protected branch](../../protected_branches.md) -1. [Create a new group](../../../group/manage.md#create-a-group). -1. [Add the user to the group](../../../group/manage.md#add-users-to-a-group), +1. [Create a new group](../../../group/index.md#create-a-group). +1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group), based on the Reporter role. @@ -195,7 +195,7 @@ granting them push access: 1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: - For a new rule, select **Add approval rule** and target the protected branch. - For an existing rule, select **Edit** and target the protected branch. -1. [Add the group](../../../group/manage.md#create-a-group) to the permission list. +1. [Add the group](../../../group/index.md#create-a-group) to the permission list. ![Update approval rule](img/update_approval_rule_v13_10.png) @@ -217,6 +217,14 @@ on a merge request, you can either add or remove approvers: Administrators can change the [merge request approvals settings](settings.md#prevent-editing-approval-rules-in-merge-requests) to prevent users from overriding approval rules for merge requests. +## Require multiple approvals for a rule + +To create an approval rule which requires more than one approval: + +- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `2` or more. +- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) + to set the `approvals_required` attribute to `2` or more. + ## Configure optional approval rules Merge request approvals can be optional for projects where approvals are diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 8f6b1a32424..94f506ba556 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -27,23 +27,17 @@ To view the diff of changes included in a merge request: 1. Select the file you want to view. 1. To hide the file browser, select **Show file browser** again. -In [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) and later, files -with many changes are collapsed to improve performance. GitLab displays the message: +Files with many changes are collapsed to improve performance. GitLab displays the message: **Some changes are not shown**. To view the changes for that file, select **Expand file**. ## Show one file at a time -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. - For larger merge requests, you can review one file at a time. You can change this setting [temporarily in a merge request](#in-a-merge-request-show-only-one-file-at-a-time), or so it [applies to all merge requests](#in-all-merge-requests-show-only-one-file-at-a-time). ### In a merge request, show only one file at a time -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) in GitLab 13.7. - To temporarily change your viewing preferences for a specific merge request: 1. Go to your merge request, and below the merge request title, select **Changes**. @@ -149,3 +143,31 @@ When there are conflicts between the source and target branch, we show an alert per conflicted file on the merge request diff: ![Example of a conflict alert shown in a merge request diff](img/conflict_ui_v15_6.png) + +## Add a comment to a merge request file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121429) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `comment_on_files`. +On GitLab.com, this feature is not available. + +You can add comments to a merge request diff file. These comments persist across +rebases and file changes. + +To add a comment to a merge request file: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Select **Changes**. +1. In the header for the file you want to comment on, select **Comment** (**{comment}**). + +## Add a comment to an image + +In merge requests and commit detail views, you can add a comment to an image. +This comment can also be a thread. + +1. Hover your mouse over the image. +1. Select the location where you want to comment. + +An icon is displayed on the image and a comment field is displayed. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 004d24778b7..6669b2883a4 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -52,8 +52,8 @@ Commit `G` is added after the cherry-pick. After a merge request is merged, you can cherry-pick all changes introduced by the merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**, and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. 1. In the upper-right corner, select **Cherry-pick**: @@ -70,8 +70,8 @@ You can cherry-pick a single commit from multiple locations in your GitLab proje To cherry-pick a commit from the list of all commits for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Commits**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Commits**. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. @@ -84,8 +84,8 @@ You can cherry-pick commits from any merge request in your project, regardless o whether the merge request is open or closed. To cherry-pick a commit from the list of commits included in a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**, and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. @@ -98,8 +98,8 @@ list of commits included in a merge request: You can cherry-pick from the list of previous commits affecting an individual file when you view that file in your project's Git repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files** and go to the file +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository** and go to the file changed by the commit. 1. Select **History**, then select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index f8c24e4067b..c930c5c6f7f 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -29,8 +29,8 @@ Prerequisite: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Depending on the type of template you want to create, scroll to either [**Merge commit message template**](#default-template-for-merge-commits) or [**Squash commit message template**](#default-template-for-squash-commits). @@ -71,6 +71,7 @@ GitLab creates a squash commit message with this template: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) `reviewed_by` variable in GitLab 15.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/199823) `local_reference` variable in GitLab 16.1. Commit message templates support these variables: @@ -82,6 +83,7 @@ Commit message templates support these variables: | `%{issues}` | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` | | `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | | `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | +| `%{local_reference}` | Local reference to the merge request. | `!72359` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | | `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | | `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index cc6ecd8398f..a36e45d159a 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -14,46 +14,72 @@ These commits are displayed on the merge request's **Commits** tab. From this tab, you can review commit messages and copy a commit's SHA when you need to [cherry-pick changes](cherry_pick_changes.md). -## Navigate merge request commits +## View commits in a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. +To see the commits included in a merge request: -To navigate commits in a merge request: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, then select your merge request. +1. To show a list of the commits in the merge request, newest first, select **Commits** . + To read more about the commit, select **Toggle commit description** (**{ellipsis_h}**) + on any commit. +1. To view the changes in the commit, select the title of the commit link. +1. To view other commits in the merge request, either: -1. Select the **Commits** tab. -1. Select the commit link. The most recent commit is displayed. -1. Navigate through the commits by either: + - Select **Prev** or **Next**. + - Use keyboard shortcuts: <kbd>X</kbd> (previous commit) and <kbd>C</kbd> (next commit). - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. +If your merge request builds upon a previous merge request, you might +need to [include more commits for context](#show-commits-from-previous-merge-requests). -![Merge requests commit navigation](img/commit_nav_v16_0.png) +### Show commits from previous merge requests -## View merge request commits in context - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. -When reviewing a merge request, it helps to have more context about the changes -made. That includes unchanged lines in unchanged files, and previous commits -that have already merged that the change is built on. +When you review a merge request, you might need information from previous commits +to help understand the commits you're reviewing. You might need more context +if another merge request: + +- Changed files your current merge request doesn't modify, so those files aren't shown + in your current merge request's diff. +- Changed files that you're modifying in your current merge request, and you need + to see the progression of work. To add previously merged commits to a merge request for more context: -1. Go to your merge request. -1. Select the **Commits** tab. -1. Scroll to the end of the list of commits, and select **Add previously merged commits**: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, then select your merge request. +1. Select **Commits**. +1. Scroll to the end of the list of commits, and select **Add previously merged commits**. 1. Select the commits that you want to add. 1. Select **Save changes**. +## Add a comment to a commit + +WARNING: +Threads created this way are lost if the commit ID changes after a +force push. + +To add discussion to a specific commit: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Commits**. +1. Below the commits, in the **Comment** field, enter a comment. +1. Save your comment as either a standalone comment, or a thread: + - To add a comment, select **Comment**. + - To start a thread, select the down arrow (**{chevron-down}**), then select **Start thread**. + ## View diffs between commits To view the changes between previously merged commits: -1. On your merge request, select the **Changes** tab. -1. By **Compare**, select the commit you want to view: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**, then select your merge request. +1. Select **Changes**. +1. By **Compare** (**{file-tree}**), select the commits to compare: ![Previously merged commits](img/previously_merged_commits_v16_0.png) -If you selected to add previously merged commits, they are displayed in the list. +If you selected to add previously merged commits for context, those commits are +also shown in the list. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index cc8f8cb2fe6..44cef4d63e5 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,8 +59,8 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find the merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. The conflicts are @@ -84,8 +84,8 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find the merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index a91d324016a..4eb4476422f 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,8 +19,8 @@ to streamline merge request creation. You can create a merge request from the list of merge requests. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. In the upper-right corner, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. @@ -95,8 +95,8 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Type a branch name and select **New branch**. 1. Above the file list, on the right side, select **Create merge request**. A merge request is created. The default branch is the target. @@ -142,9 +142,9 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select your fork of the repository. -1. On the left menu, go to **Merge requests**, and select **New merge request**. +1. On the left sidebar, select **Code > Merge requests**, and select **New merge request**. 1. In the **Source branch** dropdown list box, select the branch in your forked repository as the source branch. 1. In the **Target branch** dropdown list box, select the branch from the upstream repository as the target branch. You can set a [default target project](#set-the-default-target-project) to @@ -171,8 +171,8 @@ Prerequisites: To create a merge request by sending an email: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. In the upper-right corner, select **Email a new merge request to this project**. An email address is displayed. Copy this address. Ensure you keep this address private. @@ -216,8 +216,8 @@ scenarios when you create a new merge request: To have merge requests from a fork by default target your own fork (instead of the upstream project), you can change the default. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left menu, select **Settings > General > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f40b82a6280..f8988ae7bd7 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -12,8 +12,8 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** . +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. 1. Select **Actions** (**{ellipsis_v}**) **> Export as CSV**. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 3d92fc9a91e..1cd81e2aac2 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -57,8 +57,8 @@ information about the dependency: To view dependency information on a merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area. Dependent merge requests display information about the total number of dependencies set, such as **(status-warning)** **Depends on 1 merge request being merged**. @@ -105,8 +105,8 @@ Prerequisite: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. In **Merge request dependencies**, paste either the reference or the full URL to the merge requests that should merge before this work merges. References @@ -120,8 +120,8 @@ Prerequisite: - You must have a role in the project that allows you to edit merge requests. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Select **Edit**. 1. Scroll to **Merge request dependencies** and select **Remove** next to the reference for each dependency you want to remove. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 88e5e4a6283..6f309d2db24 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -12,7 +12,7 @@ or open threads, you can prevent it from being accepted before you [mark it as ready](#mark-merge-requests-as-ready). Flag it as a draft to disable the **Merge** button until you remove the **Draft** flag: -![Blocked Merge Button](img/draft_blocked_merge_button_v13_10.png) +![Blocked Merge Button](img/merge_request_draft_blocked_v16_0.png) ## Mark merge requests as drafts @@ -42,10 +42,7 @@ When a merge request is ready to be merged, you can remove the `Draft` flag in s - **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as ready**. Users with at least the Developer role - can also scroll to the bottom of the merge request description and select **Mark as ready**: - - ![Mark as ready](img/draft_blocked_merge_button_v13_10.png) - + can also scroll to the bottom of the merge request description and select **Mark as ready**. - **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` from the beginning of the title, or clear **Mark as draft** below the **Title** field. @@ -71,7 +68,7 @@ draft merge requests: 1. Select **Yes** to include drafts, or **No** to exclude, and press **Return** to update the list of merge requests: - ![Filter draft merge requests](img/filter_draft_merge_requests_v13_10.png) + ![Filter draft merge requests](img/filter_draft_merge_requests_v16_0.png) ## Pipelines for drafts diff --git a/doc/user/project/merge_requests/img/auto_merge_ready_v16_0.png b/doc/user/project/merge_requests/img/auto_merge_ready_v16_0.png Binary files differnew file mode 100644 index 00000000000..e68057e73a0 --- /dev/null +++ b/doc/user/project/merge_requests/img/auto_merge_ready_v16_0.png diff --git a/doc/user/project/merge_requests/img/commit_nav_v16_0.png b/doc/user/project/merge_requests/img/commit_nav_v16_0.png Binary files differdeleted file mode 100644 index 6005e516fff..00000000000 --- a/doc/user/project/merge_requests/img/commit_nav_v16_0.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/create_new_issue_v15_4.png b/doc/user/project/merge_requests/img/create_new_issue_v15_4.png Binary files differnew file mode 100644 index 00000000000..3720b601cc5 --- /dev/null +++ b/doc/user/project/merge_requests/img/create_new_issue_v15_4.png diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png Binary files differdeleted file mode 100644 index 3bac9f7fee8..00000000000 --- a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png Binary files differdeleted file mode 100644 index 4458df987d6..00000000000 --- a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v16_0.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v16_0.png Binary files differnew file mode 100644 index 00000000000..f4356aade16 --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v16_0.png diff --git a/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png b/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png Binary files differdeleted file mode 100644 index 398820f7864..00000000000 --- a/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png b/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png Binary files differdeleted file mode 100644 index c35f2c8a58b..00000000000 --- a/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_assignees_v16_0.png b/doc/user/project/merge_requests/img/merge_request_assignees_v16_0.png Binary files differnew file mode 100644 index 00000000000..114ddf612e0 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_assignees_v16_0.png diff --git a/doc/user/project/merge_requests/img/merge_request_draft_blocked_v16_0.png b/doc/user/project/merge_requests/img/merge_request_draft_blocked_v16_0.png Binary files differnew file mode 100644 index 00000000000..88fe1ec34c0 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_draft_blocked_v16_0.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differdeleted file mode 100644 index ce1d6bab536..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_pipeline.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png Binary files differdeleted file mode 100644 index dde2680ed74..00000000000 --- a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/mwps_v15_4.png b/doc/user/project/merge_requests/img/mwps_v15_4.png Binary files differdeleted file mode 100644 index f042912d470..00000000000 --- a/doc/user/project/merge_requests/img/mwps_v15_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/new-issue-one-thread_v14_3.png b/doc/user/project/merge_requests/img/new-issue-one-thread_v14_3.png Binary files differnew file mode 100644 index 00000000000..34d3a3be0a7 --- /dev/null +++ b/doc/user/project/merge_requests/img/new-issue-one-thread_v14_3.png diff --git a/doc/user/project/merge_requests/img/post_merge_pipeline_v16_0.png b/doc/user/project/merge_requests/img/post_merge_pipeline_v16_0.png Binary files differnew file mode 100644 index 00000000000..b14ce645850 --- /dev/null +++ b/doc/user/project/merge_requests/img/post_merge_pipeline_v16_0.png diff --git a/doc/user/project/merge_requests/img/unresolved_threads_v15_4.png b/doc/user/project/merge_requests/img/unresolved_threads_v15_4.png Binary files differnew file mode 100644 index 00000000000..1d1669de0f1 --- /dev/null +++ b/doc/user/project/merge_requests/img/unresolved_threads_v15_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a65c5518658..38125f623eb 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -50,8 +50,8 @@ You can view merge requests for your project, group, or yourself. To view all merge requests for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. @@ -59,8 +59,8 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd> To view merge requests for all projects in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Code > Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -68,21 +68,17 @@ If your group contains subgroups, this view also displays merge requests from th To view all merge requests assigned to you: -<!-- vale gitlab.FirstPerson = NO --> - -1. On the top bar, put your cursor in the **Search** box. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). 1. From the dropdown list, select **Merge requests assigned to me**. -<!-- vale gitlab.FirstPerson = YES --> - or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. or: -1. On the top bar, in the upper-right corner, select **Merge requests** (**{merge-request-open}**). -1. From the dropdown list, select **Assigned to you**. +1. On the left sidebar, at the top, select **Merge requests** (**{merge-request}**). +1. From the dropdown list, select **Assigned**. ## Filter the list of merge requests @@ -93,6 +89,8 @@ or: To filter the list of merge requests: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Above the list of merge requests, select **Search or filter results...**. 1. From the dropdown list, select the attribute you wish to filter by. Some examples: - [**By environment or deployment date**](#by-environment-or-deployment-date). @@ -132,17 +130,15 @@ Projects using a [fast-forward merge method](methods/index.md#fast-forward-merge do not return results, as this method does not create a merge commit. When filtering by an environment, a dropdown list presents all environments that -you can choose from: +you can choose from. -![Filter MRs by their environment](img/filtering_merge_requests_by_environment_v14_6.png) +When filtering by `Deployed-before` or `Deployed-after`: -When filtering by `Deployed-before` or `Deployed-after`, the date refers to when -the deployment to an environment (triggered by the merge commit) completed successfully. -You must enter the deploy date manually. Deploy dates -use the format `YYYY-MM-DD`, and must be quoted if you wish to specify -both a date and time (`"YYYY-MM-DD HH:MM"`): - -![Filter MRs by a deploy date](img/filtering_merge_requests_by_date_v14_6.png) +- The date refers to when the deployment to an environment (triggered by the + merge commit) completed successfully. +- You must enter the deploy date manually. +- Deploy dates use the format `YYYY-MM-DD`, and must be wrapped in double quotes (`"`) + if you want to specify both a date and time (`"YYYY-MM-DD HH:MM"`). ## Add changes to a merge request @@ -167,8 +163,8 @@ To assign the merge request to a user, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area in a merge request, or: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. 1. Search for the user you want to assign, and select the user. @@ -182,13 +178,13 @@ The merge request is added to the user's assigned merge request list. GitLab enables multiple assignees for merge requests, if multiple people are accountable for it: -![multiple assignees for merge requests sidebar](img/multiple_assignees_for_merge_requests_sidebar.png) +![multiple assignees for merge requests sidebar](img/merge_request_assignees_v16_0.png) To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. On the right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want to assign the merge request to. @@ -300,7 +296,7 @@ For a software developer working in a team: 1. Your manager: 1. Pushes a commit with their final review. 1. [Approves the merge request](approvals/index.md). - 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). + 1. Sets it to [auto-merge](merge_when_pipeline_succeeds.md) (formerly **Merge when pipeline succeeds**). 1. Your changes get deployed to production with [manual jobs](../../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. @@ -316,18 +312,19 @@ For a web developer writing a webpage for your company's website: ## Filter activity in a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115383) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `mr_activity_filters`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387070) in GitLab 16.0. Available to GitLab team members only. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `mr_activity_filters` for individual or groups of users. -On GitLab.com, this feature unavailable. +On GitLab.com, this feature is enabled for GitLab team members only. To understand the history of a merge request, filter its activity feed to show you only the items that are relevant to you. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Select a merge request. 1. Scroll to **Activity**. 1. On the right side of the page, select **Activity filter** to show the filter options. @@ -351,6 +348,78 @@ only the items that are relevant to you. Your selection persists across all merge requests. You can also change the sort order by clicking the sort button on the right. +## Resolve a thread + +> Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. + +In a merge request, you can resolve a thread when you want to finish a conversation. + +Prerequisites: + +- You must have at least the Developer role + or be the author of the change being reviewed. +- Resolvable threads can be added only to merge requests. It doesn't work + for comments in issues, commits, or snippets. + +To resolve a thread: + +1. Go to the thread. +1. Do one of the following: + - In the upper-right corner of the original comment, select **Resolve thread** (**{check-circle}**). + - Below the last reply, in the **Reply** field, select **Resolve thread**. + - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. + +At the top of the page, the number of unresolved threads is updated: + +![Count of unresolved threads](img/unresolved_threads_v15_4.png) + +### Move all unresolved threads in a merge request to an issue + +If you have multiple unresolved threads in a merge request, you can +create an issue to resolve them separately. In the merge request, at the top of the page, +select the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Resolve all with new issue**: + +![Open new issue for all unresolved threads](img/create_new_issue_v15_4.png) + +All threads are marked as resolved, and a link is added from the merge request to +the newly created issue. + +### Move one unresolved thread in a merge request to an issue + +If you have one specific unresolved thread in a merge request, you can +create an issue to resolve it separately. In the merge request, under the last reply +to the thread, next to **Resolve thread**, select **Create issue to resolve thread** (**{issue-new}**): + +![Create issue for thread](img/new-issue-one-thread_v14_3.png) + +The thread is marked as resolved, and a link is added from the merge request to +the newly created issue. + +### Prevent merge unless all threads are resolved + +You can prevent merge requests from being merged until all threads are +resolved. When this setting is enabled, the **Unresolved threads** counter in a merge request +is shown in orange when at least one thread remains unresolved. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. +1. In the **Merge checks** section, select the **All threads must be resolved** checkbox. +1. Select **Save changes**. + +### Automatically resolve threads in a merge request when they become outdated + +You can set merge requests to automatically resolve threads when lines are modified +with a new push. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. +1. In the **Merge options** section, select + **Automatically resolve merge request diff threads when they become outdated**. +1. Select **Save changes**. + +Threads are now resolved if a push makes a diff section outdated. +Threads on lines that don't change and top-level resolvable threads are not resolved. + ## Related topics - [Create a merge request](creating_merge_requests.md) diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 7588af70bd4..66c3b1fda74 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -9,29 +9,29 @@ type: reference, concepts > **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409530) to **Auto-merge** in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. Enabled by default. -NOTE: -[In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** become **Set to auto-merge**. - If you review a merge request and it's ready to merge, but the pipeline hasn't -completed yet, you can set it to merge when the pipeline succeeds (MWPS). You don't +completed yet, you can set it to auto-merge. You don't have to remember later to merge the work manually: -![Enable MWPS on a merge request](img/mwps_v15_4.png) +![Auto-merge is ready](img/auto_merge_ready_v16_0.png) + +NOTE: +[In GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/359057), **Merge when pipeline succeeds** and **Add to merge train when pipeline succeeds** are renamed **Set to auto-merge**. If the pipeline succeeds, the merge request is merged. If the pipeline fails, the author can either retry any failed jobs, or push new commits to fix the failure: - If a retried job succeeds on the second try, the merge request is merged. -- If new commits are added to the merge request, GitLab cancels the MWPS request +- If new commits are added to the merge request, GitLab cancels the request to ensure the new changes are reviewed before merge. -## Set a merge request to MWPS +## Auto-merge a merge request Prerequisites: - You must have at least the Developer role in the project. - If the project is configured to require it, all threads in the - merge request [must be resolved](../../discussions/index.md#resolve-a-thread). + merge request [must be resolved](index.md#resolve-a-thread). - The merge request must have received all required approvals. To do this when pushing from the command line, use the `merge_request.merge_when_pipeline_succeeds` @@ -39,20 +39,20 @@ To do this when pushing from the command line, use the `merge_request.merge_when To do this from the GitLab user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Scroll to the merge request reports section. 1. Optional. Select your desired merge options, such as **Delete source branch**, **Squash commits**, or **Edit commit message**. -1. Select **Merge when pipeline succeeds**. +1. Select **Auto-merge**. -If a new comment is added to the merge request after you select **Merge when pipeline succeeds**, +If a new comment is added to the merge request after you select **Auto-merge**, but before the pipeline completes, GitLab blocks the merge until you resolve all existing threads. ## Cancel an auto-merge -If a merge request is set to MWPS, you can cancel it. +If a merge request is set to auto-merge, you can cancel it. Prerequisites: @@ -62,8 +62,8 @@ Prerequisites: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Scroll to the merge request reports section. 1. Select **Cancel auto-merge**. @@ -88,8 +88,8 @@ Prerequisites: To enable this setting: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Scroll to **Merge checks**, and select **Pipelines must succeed**. This setting also prevents merge requests from being merged if there is no pipeline, which can [conflict with some rules](#merge-requests-dont-merge-when-successful-pipeline-is-required). @@ -109,9 +109,8 @@ Prerequisite: To change this behavior: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Under **Merge checks**: - Select **Pipelines must succeed**. - Select **Skipped pipelines are considered successful**. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 02bd4ed0502..7bb10303d7e 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -26,8 +26,8 @@ gitGraph ## Configure a project's merge method -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Select your desired **Merge method** from these options: - Merge commit - Merge commit with semi-linear history diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 77fd78ee0d0..c4288a7793c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -30,8 +30,8 @@ Prerequisites: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and identify your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and identify your merge request. 1. Scroll to the merge request reports area, and find the report showing when the merge request was merged. 1. Select **Revert**. @@ -55,13 +55,13 @@ Prerequisites: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. If you know the merge request that contains the commit: - 1. On the left sidebar, select **Merge requests** and identify your merge request. + 1. Select **Code > Merge requests**, then identify and select your merge request. 1. Select **Commits**, then select the title of the commit you want to revert. This displays the commit in the **Changes** tab of your merge request. 1. Select the commit hash you want to revert. GitLab displays the contents of the commit. 1. If you don't know the merge request the commit originated from: - 1. On the left sidebar, select **Repository > Commits**. + 1. Select **Code > Commits**. 1. Select the title of the commit to display full information about the commit. 1. In the upper-right corner, select **Options**, then select **Revert**. 1. In **Revert in branch**, select the branch to revert your changes into. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 0de38874304..86468af06a2 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -7,9 +7,6 @@ type: index, reference # Merge request reviews **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. - [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) to propose changes. Your team leaves [comments](../../../discussions/index.md) on @@ -26,7 +23,7 @@ For an overview, see [Merge request review](https://www.youtube.com/watch?v=2May ## Suggested reviewers **(ULTIMATE SAAS)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/alpha-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/experiment-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6. > - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10. @@ -52,9 +49,6 @@ of a merge request with new commits. ## Review a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) from GitLab Premium to GitLab Free in 13.1. - When you review a merge request, you can create comments that are visible only to you. When you're ready, you can publish them together in a single action. To start your review: @@ -62,7 +56,7 @@ To start your review: 1. Go to the merge request you want to review, and select the **Changes** tab. For more information about navigating the diffs displayed in this tab, see [Changes in merge requests](../changes.md). -1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines +1. Select **Add a comment to this line** (**{comment}**) in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can [select multiple lines](#comment-on-multiple-lines). 1. In the text area, write your first comment, then select **Start a review** below your comment. @@ -75,8 +69,7 @@ To start your review: are now visible, and any [quick actions](../../quick_actions.md) included in your comments are performed. -[In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), -if you [approve a merge request](../approvals/index.md#approve-a-merge-request) and +If you [approve a merge request](../approvals/index.md#approve-a-merge-request) and are shown in the reviewer list, a green check mark **{check-circle-filled}** displays next to your name. @@ -84,8 +77,8 @@ displays next to your name. To download the changes included in a merge request as a diff: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Plain diff**. @@ -107,8 +100,8 @@ curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git a To download the changes included in a merge request as a patch file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests**. 1. Select your merge request. 1. In the upper-right corner, select **Code > Patches**. @@ -147,7 +140,7 @@ When you submit your review, GitLab: ### Resolve or unresolve thread with a comment -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread). +Review comments can also resolve or unresolve [resolvable threads](../index.md#resolve-a-thread). To resolve or unresolve a thread when replying to a comment: 1. In the comment text area, write your comment. @@ -161,8 +154,6 @@ Pending comments display information about the action to be taken when the comme ### Add a new comment -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. - If you have a review in progress, you can also add a comment from the **Overview** tab by selecting **Add to review**: @@ -170,9 +161,6 @@ If you have a review in progress, you can also add a comment from the **Overview ### Approval Rule information for Reviewers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - [Feature flag `reviewer_approval_rules` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. - When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](../approvals/rules.md) below the name of each suggested reviewer. [Code Owners](../../codeowners/index.md) are displayed as `Codeowner` without group detail. @@ -187,8 +175,6 @@ This example shows reviewers and approval rules in a merge request sidebar: ### Request a new review -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. - After a reviewer completes their [merge request reviews](../../../discussions/index.md), the author of the merge request can request a new review from the reviewer: @@ -202,18 +188,14 @@ them a notification email. ## Comment on multiple lines -> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) select-and-drag features in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. - When commenting on a diff, you can select which lines of code your comment refers to by either: ![Comment on any diff file line](img/comment-on-any-diff-line_v13_10.png) -- Dragging the **{comment}** **comment** icon in the gutter to highlight +- Dragging **Add a comment to this line** (**{comment}**) in the gutter to highlight lines in the diff. GitLab expands the diff lines and displays a comment box. -- After starting a comment by selecting the **{comment}** **comment** icon in the +- After starting a comment by selecting **Add a comment to this line** (**{comment}**) in the gutter, select the first line number your comment refers to in the **Commenting on lines** select box. New comments default to single-line comments, unless you select a different starting line. @@ -245,8 +227,6 @@ To update multiple project merge requests at the same time: ## Bulk edit merge requests at the group level **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in GitLab 12.2. - Users with at least the Developer role can manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: @@ -315,8 +295,6 @@ the command line. ### Copy the branch name for local checkout -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. - The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request. @@ -418,9 +396,6 @@ All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) ## Cached merge request count -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327319) in GitLab 14.0. - In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 9187c5fad44..24197c5c313 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -17,8 +17,8 @@ merge request, authored by the user who suggested the changes. ## Create suggestions -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. On the secondary menu, select **Changes**. 1. Find the lines of code you want to change. - To select a single line: @@ -80,8 +80,8 @@ Prerequisites: To apply suggested changes directly from the merge request: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. Find the comment containing the suggestion you want to apply. - To apply suggestions individually, select **Apply suggestion**. - To apply multiple suggestions in a single commit, select **Add suggestion to batch**. @@ -128,8 +128,8 @@ Merge requests created from forks use the template defined in the target project To meet your project's needs, you can customize these messages and include other placeholder variables: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Scroll to **Merge suggestions**, and alter the text to meet your needs. See [Supported variables](#supported-variables) for a list of placeholders you can use in this message. @@ -155,7 +155,7 @@ For example, to customize the commit message to output ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. @@ -163,8 +163,8 @@ For example, to customize the commit message to output To reduce the number of commits added to your branch, you can apply multiple suggestions in a single commit. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. For each suggestion you want to apply, and select **Add suggestion to batch**. 1. Optional. To remove a suggestion, select **Remove from batch**. 1. After you add your desired suggestions, select **Apply suggestions**. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 075716e90c8..b9b8485021b 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -71,8 +71,8 @@ Prerequisites: To configure the default squashing behavior for all merge requests in your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. In the **Squash commits when merging** section, select your desired behavior: - **Do not allow**: Squashing is never performed, and the option is not displayed. - **Allow**: Squashing is allowed, but cleared by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 0e339c65ed5..a151a7cbf1b 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -36,8 +36,8 @@ see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869). By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Select the **Status checks must succeed** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index a7aa86a16d4..639552ca75a 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -41,11 +41,11 @@ for environments. If it's the first time the branch is deployed, the link returns a `404` error until done. During the deployment, the stop button is disabled. If the pipeline fails to deploy, the deployment information is hidden. -![Merge request pipeline](img/merge_request_pipeline.png) +![Merge request pipeline](img/post_merge_pipeline_v16_0.png) For more information, [read about pipelines](../../../ci/pipelines/index.md). -## Merge when pipeline succeeds (MWPS) +## Set auto-merge Set a merge request that looks ready to merge to [merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). @@ -65,7 +65,7 @@ faster to preview proposed modifications. ## License compliance **(ULTIMATE)** -If you have configured [License Compliance](../../compliance/license_compliance/index.md) for your project, then you can view a list of licenses that are detected for your project's dependencies. +If you have configured [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/index.md) for your project, then you can view a list of licenses that are detected for your project's dependencies. ![Merge request pipeline](img/license_compliance_widget_v15_3.png) diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 4641af262ca..47325ee7c90 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -37,9 +37,8 @@ For information about project and group milestones API, see: To view the milestone list: -1. On the top bar, select **Main menu > Projects** and find your project or - **Main menu > Groups** and find your group. -1. Select **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. In a project, GitLab displays milestones that belong to the project. In a group, GitLab displays milestones that belong to the group and all projects in the group. @@ -67,7 +66,8 @@ You might not see some milestones because they're in projects or groups you're n To do so: -1. On the top bar select **Main menu > Your work**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Your work**. 1. On the left sidebar, select **Milestones**. ### View milestone details @@ -121,8 +121,8 @@ Prerequisites: To create a milestone: -1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. 1. Select **New milestone**. 1. Enter the title. 1. Optional. Enter description, start date, and due date. @@ -140,7 +140,8 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. 1. Select a milestone's title. 1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Edit**. 1. Edit the title, start date, due date, or description. @@ -156,7 +157,8 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Milestones**. 1. Select a milestone's title. 1. In the top right corner, select **Milestone actions** (**{ellipsis_v}**) and then select **Delete**. 1. Select **Delete milestone**. @@ -181,8 +183,8 @@ Prerequisites: To promote a project milestone: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Milestones**. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. - Select the milestone title, and then select **Milestone actions** (**{ellipsis_v}**) > **Promote**. diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index a2c2ab0cc40..81c4bc20301 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -12,7 +12,7 @@ To enable the feature, ask an administrator to [enable the feature flag](../../. On GitLab.com, this feature is in private testing only. NOTE: -Model experiment tracking is an [experimental feature](../../../../policy/alpha-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. +Model experiment tracking is an [experimental feature](../../../../policy/experiment-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. When creating machine learning models, data scientists often experiment with different parameters, configurations, and feature engineering to improve the performance of the model. Keeping track of all this metadata and the associated @@ -70,8 +70,8 @@ Prerequisites: To list the current active experiments, either go to `https/-/ml/experiments` or: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Packages & registries > Model experiments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Deploy > Model experiments**. 1. To display all candidates that have been logged, along with their metrics, parameters, and metadata, select an experiment. 1. To display details for a candidate, select **Details**. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index a97fc1171fc..606f0474cb1 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -53,8 +53,8 @@ this document for an [overview on DNS records](dns_concepts.md). To add your custom domain to GitLab Pages: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -165,10 +165,10 @@ If you're using Cloudflare, check #### 4. Verify the domain's ownership -Once you have added all the DNS records: +After you have added all the DNS records: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -262,8 +262,8 @@ meet these requirements. - To add the certificate at the time you add a new domain: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > Pages**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -274,8 +274,8 @@ meet these requirements. - To add the certificate to a domain previously added: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > Pages**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -308,8 +308,8 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 91633e01ad2..15152efb80c 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,8 +42,8 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -72,8 +72,8 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). @@ -90,8 +90,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 17618146350..167c72fdc89 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,8 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select the project's name. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the **Add** (**{plus}**) dropdown list, select **New file**. 1. From the **Select a template type** dropdown list, select `.gitlab-ci.yml`. 1. From the **Apply a template** dropdown list, in the **Pages** section, select the name of your SSG. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 00635fe6db2..16d5cfcca4a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Incubation +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -33,8 +33,8 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](../index.md#menu-position-test). diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index a68ad604989..9b299b46f75 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -129,12 +129,14 @@ If you are running a self-managed instance of GitLab, ### Configure GitLab Pages in a Helm Chart (Kubernetes) instance To configure GitLab Pages on instances deployed via Helm chart (Kubernetes), use either: - -- [The `gitlab-pages` subchart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-pages/). -- [An external GitLab Pages instance](https://docs.gitlab.com/charts/advanced/external-gitlab-pages/). + +- [The `gitlab-pages` subchart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-pages/). +- [An external GitLab Pages instance](https://docs.gitlab.com/charts/advanced/external-gitlab-pages/). ## Security for GitLab Pages +### Namespaces that contain `.` + If your username is `example`, your GitLab Pages website is located at `example.gitlab.io`. GitLab allows usernames to contain a `.`, so a user named `bar.example` could create a GitLab Pages website `bar.example.gitlab.io` that effectively is a subdomain of your @@ -153,3 +155,9 @@ document.cookie = "key=value;domain=example.gitlab.io"; This issue doesn't affect users with a custom domain, or users who don't set any cookies manually with JavaScript. + +### Shared cookies + +By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. + +To ensure each project uses different cookies, enable the Pages [unique domains](introduction.md#enable-unique-domains) feature for your project. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 05d0b461fea..73bfe018a7d 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -66,8 +66,8 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. If this path is not visible, select **Deployments > Pages**. [This location is part of an experiment](index.md#menu-position-test). @@ -94,6 +94,25 @@ the group must be at the top level and not a subgroup. For [project websites](../../project/pages/getting_started_part_one.md#project-website-examples), you can create your project first and access it under `http(s)://namespace.example.io/projectname`. +## Enable unique domains + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9347) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `pages_unique_domain`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `pages_unique_domain`. +On GitLab.com, by default this feature is available. + +By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. + +To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Pages**. +1. Select the **Use unique domain** checkbox. +1. Select **Save changes**. + ## Specific configuration options for Pages Learn how to set up GitLab CI/CD for specific use cases. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 1d279436d2c..6958b69061a 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -30,19 +30,23 @@ When a branch is protected, the default behavior enforces these restrictions on |:-------------------------|:------------------------------------------------------------------| | Protect a branch | At least the Maintainer role. | | Push to the branch | Anyone with **Allowed** permission. (1) | -| Force push to the branch | No one. | +| Force push to the branch | No one. (3) | | Delete the branch | No one. (2) | 1. Users with the Developer role can create a project in a group, but might not be allowed to initially push to the [default branch](repository/branches/default.md). 1. No one can delete a protected branch using Git commands, however, users with at least Maintainer role can [delete a protected branch from the UI or API](#delete-a-protected-branch). +1. If the `group_protected_branches` feature flag is enabled _and_ the same branch is + protected at both the group and project levels, force push settings configured + for that branch at the project level are ignored. All other protections continue + to use project level settings. ### When a branch matches multiple rules When a branch matches multiple rules, the **most permissive rule** determines the level of protection for the branch. For example, consider these rules, which include -[wildcards](#configure-multiple-protected-branches-by-using-a-wildcard): +[wildcards](#protect-multiple-branches-with-wildcard-rules): | Branch name pattern | Allowed to merge | Allowed to push and merge | |---------------------|------------------------|-----------------| @@ -77,29 +81,59 @@ that matches `v1.x` must set `Allowed to push and merge` to `No one`, like this: Administrators can set a default branch protection level in the [Admin Area](../project/repository/branches/default.md#instance-level-default-branch-protection). -## Configure a protected branch +## Add protection to existing branches Configure protected branches for all projects in a group, or just for a project. -### For all projects in a group **(PREMIUM)** +### For one project + +Prerequisites: + +- You must have at least the Maintainer role. +- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions + on a protected branch, the group must be added to the project. + +To protect a branch: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown list, select the branch you want to protect. +1. From the **Allowed to merge** list, select a role that can merge into this branch. +1. From the **Allowed to push and merge** list, select a role that can push to this branch. + + NOTE: + In GitLab Premium and Ultimate, you can also add groups or individual users + to **Allowed to merge** and **Allowed to push and merge**. + +1. Select **Protect**. + +The protected branch displays in the list of protected branches. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 behind a feature flag, disabled by default. +### For all projects in a group **(PREMIUM)** -Group owners can create protected branches for a group. These settings are inherited by all projects in the group and can't be overridden by project settings. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `group_protected_branches`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) +To make it available, ask an administrator to +[enable the feature flag](../../administration/feature_flags.md) named `group_protected_branches`. On GitLab.com, this feature is not available. +Group owners can create protected branches for a group. These settings are inherited +by all projects in the group and can't be overridden by project settings. If a +specific branch is configured with **Allowed to force push** settings at both the +group and project levels, the **Allowed to force push** setting at the _project_ level +is ignored in favor of the group level setting. + Prerequisite: - You must have the Owner role in the group. To protect a branch for all the projects in a group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. In the **Branch** text box, type the branch name or a wildcard. 1. From the **Allowed to merge** list, select a role that can merge into this branch. @@ -108,31 +142,12 @@ To protect a branch for all the projects in a group: The protected branch is added to the list of protected branches. -### For a project - -Prerequisite: - -- You must have at least the Maintainer role. -- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions - on a protected branch, the group must be added to the project. - -To protect a branch: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Protected branches**. -1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. -1. Select **Protect**. - -The protected branch displays in the list of protected branches. - -## Configure multiple protected branches by using a wildcard +## Protect multiple branches with wildcard rules -If both a specific rule and a wildcard rule apply to the same branch, the most -permissive rule controls how the branch behaves. For merge controls to work properly, -set **Allowed to push and merge** to a broader set of users than **Allowed to merge**. +When using wildcards, multiple rules can apply to a single branch. +If more than one rule applies to a branch, the _most permissive_ rule controls +how the branch behaves. For merge controls to work properly, set +**Allowed to push and merge** to a broader set of users than **Allowed to merge**. Prerequisite: @@ -140,8 +155,8 @@ Prerequisite: To protect multiple branches at the same time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, type the branch name and a wildcard. For example: @@ -152,19 +167,21 @@ To protect multiple branches at the same time: | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to merge** list, select a role that can merge into + this branch. +1. From the **Allowed to push and merge** list, select a role that can + push to this branch. In GitLab Premium or Ultimate, you can also add groups or individual users. 1. Select **Protect**. The protected branch displays in the list of protected branches. -## Create a protected branch +## Create a new branch with protections -Users with at least the Developer role can create a protected branch. +Users with at least the Developer role can create new protected branches. Prerequisites: -- **Allowed to push and merge** is set to **No one** +- **Allowed to push and merge** is set to **No one**. - **Allowed to merge** is set to **Developers**. You can create a protected branch by using the UI or API only. @@ -173,8 +190,8 @@ from the command line or from a Git client application. To create a new branch through the user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Select **New branch**. 1. Fill in the branch name and select an existing branch, tag, or commit to base the new branch on. Only existing protected branches and commits @@ -186,8 +203,8 @@ You can force everyone to submit a merge request, rather than allowing them to check in directly to a protected branch. This setting is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. @@ -198,8 +215,8 @@ like the [GitLab workflow](../../topics/gitlab_flow.md). You can allow everyone with write access to push to the protected branch. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select **Developers + Maintainers**. @@ -226,8 +243,8 @@ Prerequisites: To allow a deploy key to push to a protected branch: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** list, select the deploy key. @@ -245,8 +262,8 @@ protected branches. To protect a new branch and enable force push: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. @@ -257,23 +274,49 @@ To protect a new branch and enable force push: To enable force pushes on branches that are already protected: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. Members who can push to this branch can now also force push. +### When a branch matches multiple rules + +When a branch matches multiple rules, the **most permissive rule** determines the +level of protection for the branch. For example, consider these rules, which include +[wildcards](#protect-multiple-branches-with-wildcard-rules): + +| Branch name pattern | Allow force push | +|---------------------|------------------| +| `v1.x` | Yes | +| `v1.*` | No | +| `v*` | No | + +A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`. +As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are: + +- **Allow force push:** Of the three settings, `Yes` is most permissive, + and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*` + (which each have stricter permissions), any user that can push to this branch can also force push. + +NOTE: +Force push settings for a branch at the project level are overridden by group level settings +if the `group_protected_branches` feature flag is enabled and a group owner has set +[group level protection for the same branch](#for-all-projects-in-a-group). + ## Require Code Owner approval on a protected branch **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. For a protected branch, you can require at least one approval by a [Code Owner](codeowners/index.md). +If a branch is protected by multiple rules, code owner approval is required if _any_ of +the applicable rules have **Required approval from code owners** enabled. To protect a new branch and enable Code Owner's approval: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. @@ -282,8 +325,8 @@ To protect a new branch and enable Code Owner's approval: To enable Code Owner's approval on branches that are already protected: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected branches**. 1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. @@ -314,8 +357,8 @@ for details about the pipelines security model. Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, type the branch name. 1. Select **Yes, delete protected branch**. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 3af475afa4f..0449c9867e2 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -31,15 +31,20 @@ Prerequisites: - You must have at least the Maintainer role for the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected tags**. 1. To protect a single tag, select **Tag**, then choose your tag from the dropdown list. 1. To protect all tags with names matching a string: 1. Select **Tag**. 1. Enter the string to use for tag matching. Wildcards (`*`) are supported. 1. Select **Create wildcard**. -1. In **Allowed to create** , select either the users or roles that may create protected tags. +1. In **Allowed to create** , select roles that may create protected tags. + + NOTE: + In GitLab Premium and Ultimate, you can also add groups or individual users + to **Allowed to create**. + 1. Select **Protect**. The protected tag (or wildcard) displays in the **Protected tags** list. @@ -105,8 +110,8 @@ Prerequisites: To allow a deploy key to create a protected tag: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Protected tags**. 1. From the **Tag** dropdown list, select the tag you want to protect. 1. From the **Allowed to create** list, select the deploy key. @@ -123,8 +128,8 @@ Prerequisite: To do this: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Tags**. 1. Next to the tag you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 1f85490795f..368a59e69b0 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -35,7 +35,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | -| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | +| `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI integrations, such as Jenkins. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | | `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 2c52a5d743a..3e8ce009740 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -129,8 +129,9 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). -| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{check-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). -| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{check-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). +| `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). +| `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). +| `/unlink <issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove link with to the provided issue. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414400) in GitLab 16.1). ## Work items @@ -162,7 +163,8 @@ The following quick actions can be applied through the description field when ed | `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. -| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `Issue`, `Task`, `Objective` and `Key Result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0 [with a flag](../../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. +| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `Issue`, `Task`, `Objective` and `Key Result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. +| `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) and `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index d0c44b7e837..6bcc57d5916 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -74,8 +74,8 @@ Prerequisites: To create a release in the Releases page: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Releases** and select **New release**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Build > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. @@ -215,8 +215,8 @@ To delete a release, use either the In the UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Releases**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Deploy > Releases**. 1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index bd3cfd26f1b..c5fb3838b11 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -23,7 +23,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \ "Created using the release-cli $EXTRA_DESCRIPTION" \ --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" \ --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" \ - --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} + --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}" ``` ## Install the `release-cli` for the Shell executor **(FREE)** @@ -37,13 +37,8 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ### Install on Unix/Linux -1. Download the binary for your system from S3, in the following example for amd64 systems: - - ```shell - curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64" - ``` - - Or from the GitLab Package Registry: +1. Download the binary for your system from the GitLab Package Registry. + For example, if you use an amd64 system: ```shell curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-linux-amd64" @@ -60,7 +55,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ```shell $ release-cli -v - release-cli version 0.6.0 + release-cli version 0.15.0 ``` ### Install on Windows PowerShell @@ -74,7 +69,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av 1. Download the executable file: ```shell - PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" + PS C:\> Invoke-WebRequest -Uri "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" Directory: C:\GitLab\Release-CLI Mode LastWriteTime Length Name @@ -93,5 +88,5 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ```shell PS C:\> release-cli -v - release-cli version 0.6.0 + release-cli version 0.15.0 ``` diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index d4156de2ebe..6a9d0c73e9a 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -14,7 +14,7 @@ FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. WARNING: -This feature is in [Beta](../../../policy/alpha-beta-support.md#beta) and subject to change without notice. +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. You can use remote development to write and compile code hosted on GitLab. With remote development, you can: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index e58cc0bf6a4..100450aefe7 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -42,8 +42,8 @@ Prerequisites: To update the default branch for an individual [project](../../index.md): -1. On the top bar, select **Main menu > Projects** and find your project. -1. In the left navigation menu, go to **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Branch defaults**. For **Default branch**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request @@ -68,8 +68,9 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. 1. Select **Save changes**. @@ -84,8 +85,8 @@ overrides it. Users with the Owner role of groups and subgroups can configure the default branch name for a group: -1. On the top bar, select **Main menu > Group** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. 1. Select **Save changes**. @@ -95,6 +96,8 @@ unless a subgroup configuration overrides it. ## Protect initial default branches **(FREE SELF)** +> Full protection after initial push [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0. + GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md) to apply to every repository's [default branch](#default-branch) at the [instance level](#instance-level-default-branch-protection) and @@ -108,6 +111,8 @@ at the [instance level](#instance-level-default-branch-protection) and but cannot force push. - **Fully protected** - Developers cannot push new commits, but maintainers can. No one can force push. +- **Fully protected after initial push** - Developers can push the initial commit + to a repository, but none afterward. Maintainers can always push. No one can force push. ### Instance-level default branch protection **(FREE SELF)** @@ -120,8 +125,9 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). 1. To allow group owners to override the instance's default branch protection, select @@ -137,8 +143,9 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand the **Default branch** section. 1. Clear the **Allow owners to manage default branch protection per group** checkbox. 1. Select **Save changes**. @@ -157,8 +164,8 @@ can be overridden on a per-group basis by the group's owner. In [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). 1. Select **Save changes**. diff --git a/doc/user/project/repository/branches/img/delete_merged_branches.png b/doc/user/project/repository/branches/img/delete_merged_branches.png Binary files differdeleted file mode 100644 index 649a758b95f..00000000000 --- a/doc/user/project/repository/branches/img/delete_merged_branches.png +++ /dev/null diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 7c09ce5c580..e43efca600a 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -29,8 +29,8 @@ Branches are the foundation of development in a project: To create a new branch from the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. On the top right, select **New branch**. 1. Enter a **Branch name**. 1. In **Create from**, select the base of your branch: an existing branch, an existing @@ -52,7 +52,7 @@ Prerequisites: To add a [default branch](default.md) to an empty project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Scroll to **The repository for this project is empty** and select the type of file you want to add. 1. In the Web IDE, make any desired changes to this file, then select **Create commit**. @@ -62,7 +62,14 @@ GitLab creates a default branch and adds your file to it. ### From an issue +Prerequisites: + +- You must have at least the Developer role in the project. + When viewing an issue, you can create an associated branch directly from that page. +Branches created this way use the +[default pattern for branch names from issues](#configure-default-pattern-for-branch-names-from-issues), +including variables. Prerequisites: @@ -70,8 +77,8 @@ Prerequisites: To create a branch from an issue: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues** (**{issues}**) and find your issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues** and find your issue. 1. Below the issue description, find the **Create merge request** dropdown list, and select **{chevron-down}** to display the dropdown list. 1. Select **Create branch**. A default **Branch name** is provided, based on the @@ -104,8 +111,8 @@ You can manage your branches: To view and manage your branches in the GitLab user interface: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. On this page, you can: @@ -142,8 +149,8 @@ Prerequisites: To view the **Branch rules overview** list: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Branch Rules** to view all branches with protections. - To add protections to a new branch: 1. Select **Add branch rule**. @@ -193,8 +200,9 @@ Prerequisites: To change the default pattern for branches created from issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository** and expand **Branch defaults**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. +1. Expand **Branch defaults**. 1. Scroll to **Branch name template** and enter a value. The field supports these variables: - `%{id}`: The numeric ID of the issue. - `%{title}`: The title of the issue, modified to use only characters acceptable in Git branch names. @@ -230,8 +238,8 @@ new changes. It uses the merge base, not the actual commit content, to compare b To compare branches in a repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Compare revisions**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Compare revisions**. 1. Select the **Source** branch to search for your desired branch. Exact matches are shown first. You can refine your search with operators: - `^` matches the beginning of the branch name: `^feat` matches `feat/user-authentication`. @@ -244,15 +252,22 @@ To compare branches in a repository: ## Delete merged branches -![Delete merged branches](img/delete_merged_branches.png) +Merged branches can be deleted in bulk if they meet all of these criteria: + +- They are not [protected branches](../../protected_branches.md). +- They have been merged into the project's default branch. + +Prerequisites: + +- You must have at least the Developer role in the project. -This feature allows merged branches to be deleted in bulk. Only branches that -have been merged into the project's default branch and -[are not protected](../../protected_branches.md) are deleted as part of -this operation. +To do this: -It's particularly useful to clean up old branches that were not deleted -automatically when a merge request was merged. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. +1. On the upper right corner of the page, select **More** **{ellipsis_v}**. +1. Select **Delete merged branches**. +1. In the modal window, enter the word `delete` to confirm, then select **Delete merged branches**. ## Related topics @@ -308,8 +323,8 @@ Error: Could not set the default branch. Do you have a branch named 'HEAD' in yo To fix this problem: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Branches**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Branches**. 1. Search for a branch named `HEAD`. 1. Make sure the branch has no uncommitted changes. 1. Select **Delete branch**, then **Yes, delete branch**. diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md index 5de55db5ad4..dd1fa3f4c8b 100644 --- a/doc/user/project/repository/code_suggestions.md +++ b/doc/user/project/repository/code_suggestions.md @@ -7,19 +7,21 @@ type: index, reference # Code Suggestions (Beta) **(FREE SAAS)** -> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/alpha-beta-support.md#beta) for early access Ultimate customers. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/alpha-beta-support.md#beta). +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/experiment-beta-support.md#beta) for early access Ultimate customers. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/experiment-beta-support.md#beta). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1. +> - [Default to third-party AI services](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. WARNING: -This feature is in [Beta](/ee/policy/alpha-beta-support.md#beta). -Code Suggestions use generative AI to suggest code while you're developing. -Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. +This feature is in [Beta](/ee/policy/experiment-beta-support.md#beta). +Due to high demand, this feature may have unscheduled downtime and Code Suggestions in IDEs may be delayed. Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your feedback. -Use Code Suggestions to write code more efficiently by viewing code suggestions +Code Suggestions use generative AI to suggest code while you're developing. +Use Code Suggestions to write code more efficiently by viewing Code Suggestions as you type. Depending on the cursor position, the extension either: - Provides entire code snippets, like generating functions. @@ -27,47 +29,68 @@ as you type. Depending on the cursor position, the extension either: To accept a suggestion, press <kbd>Tab</kbd>. -Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. +Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. [Additional IDE extension support](https://gitlab.com/groups/gitlab-org/-/epics/10542) is planned for the near future. ## Supported languages -Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). The best results from Code Suggestions are expected for these languages: +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). + +Language support varies depending on which AI model serves Code Suggestions. To use Code Suggestions entirely within GitLab cloud infrastructure, disable third-party AI services. To receive higher quality suggestions, [enable third-party AI services](#third-party-ai-services-controls). -- C/C++ -- C# -- Go -- Java -- JavaScript -- Python -- PHP -- Ruby -- Rust -- Scala -- TypeScript +The best results from Code Suggestions are expected for these languages: + +- **Third-party AI services (Google Codey)**: Go, Google Cloud CLI, Google SQL, Java, JavaScript, Kubernetes Resource Model (KRM), Python, Terraform, TypeScript. +- **GitLab first-party AI model**: C/C++, C#, Go, Java, JavaScript, Python, PHP, Ruby, Rust, Scala, TypeScript. Suggestions may be mixed for other languages. Using natural language code comments to request completions may also not function as expected. -GitLab is continuously improving the model and expects to support an additional seven languages soon, as well as natural language code comments. +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. + +We are making improvements to the Code Suggestions underlying AI model weekly to improve the quality of suggestions. Please remember that AI is non-deterministic, so you may not get the same suggestion week to week. Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). +## Enable Code Suggestions for an individual user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](/ee/policy/experiment-beta-support.md#beta). + +Each user can enable Code Suggestions for themselves: + +1. On the left sidebar, select your avatar. +1. On the left sidebar, select **Preferences**. +1. In the **Code Suggestions** section, select **Enable Code Suggestions**. +1. Select **Save changes**. + +NOTE: +If Code Suggestions is [enabled for the group](../../group/manage.md#enable-code-suggestions), the group setting overrides the user setting. + +## Enable Code Suggestions in WebIDE + +Prerequisites: + +- Code Suggestions must be [enabled for the top-level group](../../group/manage.md#enable-code-suggestions). +- Code Suggestions must be [enabled for your user account](#enable-code-suggestions-for-an-individual-user). +- You must be a GitLab team member. + +Code Suggestions work automatically in the [GitLab WebIDE](../../project/web_ide/index.md) if the above prerequisites are met. To disable Code Suggestions in the WebIDE, disable the user account setting. + +NOTE: +Disabling in the WebIDE will also disable in any other IDEs you use locally like VS Code. Support for [more granular control per IDE](https://gitlab.com/groups/gitlab-org/-/epics/10624) is proposed. + ## Enable Code Suggestions in VS Code Prerequisites: -- Your group owner must enable the [group level code suggestions setting](../../group/manage.md#group-code-suggestions). -- You must have [a personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` and `read_user` scopes. +- Code Suggestions must be [enabled for the top-level group](../../group/manage.md#enable-code-suggestions). +- Code Suggestions must be [enabled for your user account](#enable-code-suggestions-for-an-individual-user). +- Completed the [setup instructions](https://gitlab.com/gitlab-org/gitlab-vscode-extension#setup) for the GitLab Visual Studio Code Extension. To enable Code Suggestions in VS Code: -1. Download and configure the +1. Download and install the [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) for Visual Studio Code. -1. In **GitLab: Add Account to VS Code on Mac**, add your GitLab work account to the VS Code extension: - - In macOS, press <kbd>Shift</kbd> + <kbd>Command</kbd> + <kbd>P</kbd>. - - In Windows, press <kbd>Shift</kbd> + <kbd>Control</kbd> + <kbd>P</kbd>. -1. Provide your GitLab instance URL. A default is provided. -1. Provide your personal access token. +1. Complete the [setup instructions](https://gitlab.com/gitlab-org/gitlab-vscode-extension#setup) for the extension. 1. After your GitLab account connects successfully, in the left sidebar, select **Extensions**. 1. Find the **GitLab workflow** extension, select **Settings** (**{settings}**), and select **Extension Settings**. 1. Enable **GitLab > AI Assisted Code Suggestions**. @@ -81,6 +104,51 @@ Start typing and receive suggestions for your GitLab projects. <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> </figure> +## Enable Code Suggestions in other IDEs and editors + +We have experimental support for Code Suggestions in Visual Studio, JetBrains, Neovim, Emacs, Sublime, etc. + +More details in this [blog](https://about.gitlab.com/blog/2023/06/01/extending-code-suggestions/). + +## Why aren't Code Suggestions displayed? + +If Code Suggestions are not displayed, try the following troubleshooting steps. + +In GitLab, ensure Code Suggestions is enabled: + +- [For your user account](#enable-code-suggestions-for-an-individual-user). +- [For *all* top-level groups your account belongs to](../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. + +In VS Code: + +- Ensure [your IDE is configured properly](#enable-code-suggestions-in-vs-code). + +To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. + +### Authentication troubleshooting + +If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, specifically the token system. To resolve the issue, please follow these troubleshooting steps: + +- Remove the existing PAT from your GitLab account settings. +- Reauthorize your GitLab account in VSCode using OAuth. +- Test the code suggestions feature with different file extensions to verify if the issue is resolved. + +## Third-party AI services controls + +Organizations can opt to use Code Suggestions entirely within GitLab cloud infrastructure. This option can be controlled with the top-level group [Third-party AI setting](../../group/manage.md#enable-third-party-ai-features). + +Having the third-party AI setting enabled will allow Code Suggestions to use third-party AI services, which is likely to produce higher quality results. Please note that language support varies between the two options and will change over time. + +To use Code Suggestions entirely within GitLab’s cloud infrastructure, disable third-party AI services. You can disable Code Suggestions entirely in [your user profile settings](#enable-code-suggestions-for-an-individual-user). + +## Stability and performance + +This feature is currently in [Beta](/ee/policy/experiment-beta-support.md#beta). +While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, +we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime +of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + ## Code Suggestions data usage Code Suggestions is a generative artificial intelligence (AI) model hosted on GitLab.com. @@ -89,8 +157,12 @@ Your personal access token enables a secure API connection to GitLab.com. This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, and the generated suggestion is transmitted back to VS Code. +Depending on your settings, different ML models will be used to provide Code Suggestions. GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) for third-party AI powered Code Suggestions. The sections below refer only to GitLab first-party AI Model. + ### Data privacy +This section applies only to customers who have third-party AI services disabled. + Code Suggestions operate completely in the GitLab.com infrastructure, providing the same level of [security](https://about.gitlab.com/security/) as any other feature of GitLab.com, and processing any personal data in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). @@ -103,6 +175,8 @@ Your data also never leaves GitLab.com. All training and inference is done in Gi ### Training data +This section applies only to customers who have third-party AI services disabled. + Code Suggestions uses open source pre-trained base models from the [CodeGen family](https://openreview.net/forum?id=iaYcJKpY2B_) including CodeGen-MULTI and CodeGen-NL. We then re-train and fine-tune these base models with a customized open source dataset to enable multi-language @@ -111,41 +185,29 @@ programming languages from [The Pile](https://pile.eleuther.ai/) and the [Google BigQuery source code dataset](https://cloud.google.com/blog/topics/public-datasets/github-on-bigquery-analyze-all-the-open-source-code). We then process this raw dataset against heuristics that aim to increase the quality of the dataset. -The Code Suggestions model is not trained on GitLab customer data. - -### Off by default - -Code Suggestions are off by default and require a group owner to enable the feature with a group-level setting. - -After the group-level setting is enabled, developers using Visual Studio Code with the -[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) can connect -to GitLab.com by using a GitLab -[personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` -and `read_user` scopes. +The Code Suggestions model is not trained on GitLab customer or user data. ## Progressive enhancement -This feature is designed as a progressive enhancement to the existing VS Code GitLab Workflow plugin. +This feature is designed as a progressive enhancement to developers IDEs. Code Suggestions offer a completion if the machine learning engine can generate a recommendation. In the event of a connection issue or model inference failure, the feature gracefully degrades. -Code Suggestions do not prevent you from writing code in VS Code. +Code Suggestions do not prevent you from writing code in your IDE. ### Internet connectivity -Code Suggestions only work when you have internet connectivity and can access GitLab.com. -Code Suggestions are not available for self-managed customers, nor customers operating within an offline environment. +Code Suggestions does not work with offline environments. -### Stability and performance +To use Code Suggestions: -This feature is currently in [Beta](/ee/policy/alpha-beta-support.md#beta). -While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, -we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime -of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to -mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. +- On GitLab.com, you must have an internet connection and be able to access GitLab. +- In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. + +[Self-managed support via a proxy to GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/10528) has been proposed. ### Model accuracy and quality -While in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +Regardless of whether third-party AI services are enabled, while in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. We strongly encourage all beta users to leverage GitLab native [Code Quality Scanning](../../../ci/testing/code_quality.md) and [Security Scanning](../../application_security/index.md) capabilities. @@ -174,6 +236,7 @@ However, Code Suggestions may generate suggestions that are: We are also aware of specific situations that can produce unexpected or incoherent results including: +- Suggestions written in the middle of existing functions, or "fill in the middle." - Suggestions based on natural language code comments. - Suggestions that mixed programming languages in unexpected ways. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index e22dc549a4a..dece959bdc9 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -14,8 +14,8 @@ File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fu To search for a file: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. In the upper right, select **Find file**. 1. In the search box, start typing the filename. 1. From the dropdown list, select the file. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 74d765fa7fe..a6bb02989a3 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -54,17 +54,13 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates ### From the UI -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `synchronize_fork`. -On GitLab.com, this feature is available for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 16.0. Feature flag `synchronize_fork` removed. To update your fork from the GitLab UI: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the secondary menu, select **Personal**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. Select the fork you want to update. 1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**) information box to determine if your fork is ahead, behind, or both. In this example, @@ -185,8 +181,8 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To remove a fork relationship: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Remove fork relationship** section, select **Remove fork relationship**. 1. To confirm, enter the project path and select **Confirm**. @@ -199,7 +195,6 @@ to share objects with another repository: ## Related topics -- GitLab blog post: [Keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/) - GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/32469) ## Troubleshooting diff --git a/doc/user/project/repository/geojson.md b/doc/user/project/repository/geojson.md new file mode 100644 index 00000000000..723121bc923 --- /dev/null +++ b/doc/user/project/repository/geojson.md @@ -0,0 +1,19 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: reference +--- + +# GeoJSON files **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14134) in GitLab 16.1. + +A GeoJSON file is a format for encoding geographical data structures using JavaScript Object Notation (JSON). +It is commonly used for representing geographic features, such as points, lines, and polygons, along with their associated attributes. + +When added to a repository, files with a `.geojson` extension are rendered as a map containing the GeoJSON data when viewed in GitLab. + +Map data comes from [OpenStreetMap](https://www.openstreetmap.org/) under the [Open Database License](https://www.openstreetmap.org/copyright). + +![GeoJSON file rendered as a map](img/geo_json_file_rendered_v16_1.png) diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index fbf29bddd46..baac2a788be 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -10,7 +10,16 @@ description: "Documentation on Git file blame." [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and -commit hash. To view it for a file: +commit hash. + +## View blame for a file + +Prerequisites: + +- The file type must be text-based. The GitLab UI does not display + `git blame` results for binary files. + +To view the blame for a file: 1. Go to your project's **Repository > Files**. 1. Select the file you want to review. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index a2dd2488961..839ab33808b 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -121,7 +121,7 @@ To add a GPG key to your user settings: 1. Sign in to GitLab. 1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **GPG Keys** (**{key}**). 1. In **Key**, paste your _public_ key. 1. To add the key to your account, select **Add key**. GitLab shows the key's fingerprint, email address, and creation date: @@ -226,11 +226,11 @@ Prerequisites: You can review commits for a merge request, or for an entire project: 1. To review commits for a project: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Repository > Commits**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Commits**. 1. To review commits for a merge request: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Merge requests**, then select your merge request. 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** or **Unverified** badge, depending on the verification status of the GPG @@ -255,7 +255,7 @@ To revoke a GPG key: 1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. ## Remove a GPG key @@ -270,7 +270,7 @@ To remove a GPG key from your account: 1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **GPG Keys** (**{key}**). 1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. If you must unverify both future and past commits, diff --git a/doc/user/project/repository/img/geo_json_file_rendered_v16_1.png b/doc/user/project/repository/img/geo_json_file_rendered_v16_1.png Binary files differnew file mode 100644 index 00000000000..b67a7bc3fda --- /dev/null +++ b/doc/user/project/repository/img/geo_json_file_rendered_v16_1.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 1526c7b4dc2..d3d9b202e63 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,7 +25,7 @@ GitLab. ## Cleaner diffs and raw diffs -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. > - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 0563f747e8d..550d4535adb 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -44,7 +44,7 @@ and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 9f72b8f29b2..733310a0b4d 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -34,14 +34,14 @@ Mirror a repository when: ## Create a repository mirror -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original repository is only displayed to users with the Maintainer role @@ -59,13 +59,38 @@ Prerequisite: 1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) to ensure it is correct. 1. To prevent force-pushing over diverged refs, select [**Keep divergent refs**](push.md#keep-divergent-refs). -1. Optional. Select [**Mirror only protected branches**](#mirror-only-protected-branches). +1. Optional. To limit the number of branches mirrored, select + **Mirror only protected branches** or enter a regex in **Mirror specific branches**. 1. Select **Mirror repository**. If you select `SSH public key` as your authentication method, GitLab generates a public key for your GitLab repository. You must provide this key to the non-GitLab server. For more information, see [Get your SSH public key](#get-your-ssh-public-key). +### Mirror only protected branches + +You can choose to mirror only the +[protected branches](../../protected_branches.md) in the mirroring project, +either from or to your remote repository. For [pull mirroring](pull.md), +non-protected branches in the mirroring project are not mirrored and can diverge. + +To use this option, select **Only mirror protected branches** when you create a repository mirror. + +### Mirror specific branches **(PREMIUM)** + +> - Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. + +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is available. + +To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), +enter a regular expression into the **Mirror specific branches** field. Branches with names that +do not match the regular expression are not mirrored. + ## Update a mirror When the mirror repository is updated, all new branches, tags, and commits are visible in the @@ -88,37 +113,13 @@ Prerequisite: - You must have at least the Maintainer role for the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories** and identify the mirror to update. 1. Select **Update now** (**{retry}**): ![Repository mirroring force update user interface](img/repository_mirroring_force_update.png) -## Mirror only protected branches - -You can choose to mirror only the -[protected branches](../../protected_branches.md) in the mirroring project, -either from or to your remote repository. For [pull mirroring](pull.md), -non-protected branches in the mirroring project are not mirrored and can diverge. - -To use this option, select **Only mirror protected branches** when you create a repository mirror. - -## Mirror specific branches - -> - Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default the field `mirror_branch_regex` is available. -To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) -named `mirror_only_branches_match_regex`. -On GitLab.com, this feature is available. - -To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), -enter a regular expression into the **Mirror specific branches** field. Branches with names that -do not match the regular expression are not mirrored. - ## Authentication methods for mirrors When you create a mirror, you must configure the authentication method for it. @@ -155,8 +156,8 @@ When you mirror a repository and select the **SSH public key** as your authentication method, GitLab generates a public key for you. The non-GitLab server needs this key to establish trust with your GitLab repository. To copy your SSH public key: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories**. 1. Identify the correct repository, and select **Copy SSH public key** (**{copy-to-clipboard}**). @@ -183,6 +184,7 @@ for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) +- [Codeberg](https://docs.codeberg.org/security/ssh-fingerprint/) - [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints) - [GitLab.com](../../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) @@ -263,8 +265,8 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. If no repository owner is specified, delete and add the URL again in this format, replacing `OWNER`, `ACCOUNTNAME`, `PATH_TO_REPO`, and `REPONAME` with your values: @@ -344,8 +346,8 @@ Prerequisites: To resolve the issue: 1. [Verify the host key](#verify-a-host-key). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. To refresh the keys, either: diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 2b8470b9e3d..1463e0de0f1 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -60,8 +60,8 @@ Prerequisite: with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter the **Git repository URL**. Include the username in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 11093958650..9da8ce7acc5 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -34,8 +34,8 @@ displays an error. To set up push mirroring for an existing project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a repository URL. 1. In the **Mirror direction** dropdown list, select **Push**. @@ -79,8 +79,15 @@ To configure a mirror from GitLab to GitHub: 1. Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `public_repo` selected. -1. Enter a **Git repository URL** with this format: - `https://<your_access_token>@github.com/<github_group>/<github_project>.git`. +1. Enter a **Git repository URL** with this format, changing the variables as needed: + + ```plaintext + https://USERNAME@github.com/GROUP/PROJECT.git + ``` + + - `USERNAME`: The username of the owner of the personal access token. + - `GROUP`: The group on GitHub. + - `PROJECT`: The project on GitHub. 1. For **Password**, enter your GitHub personal access token. 1. Select **Mirror repository**. @@ -149,7 +156,7 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. 1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. -1. On the left sidebar, select **Settings > Repository**, and then expand **Mirroring repositories**. +1. Select **Settings > Repository**, and then expand **Mirroring repositories**. 1. Fill in the **Git repository URL** field using this format: ```plaintext diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 28afba375fc..fbadc9b84a3 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -19,6 +19,7 @@ can and can't be pushed to your repository. While GitLab offers GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules. You can test them at the [regex101 regex tester](https://regex101.com/). +Each regular expression is limited to 255 characters. For custom push rules use [server hooks](../../../administration/server_hooks.md). @@ -36,8 +37,9 @@ Prerequisite: To create global push rules: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Push Rules**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Push Rules**. 1. Expand **Push rules**. 1. Set the rule you want. 1. Select **Save push rules**. @@ -48,8 +50,8 @@ The push rule of an individual project overrides the global push rule. To override global push rules for a specific project, or to update the rules for an existing project to match new global push rules: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. 1. Expand **Push rules**. 1. Set the rule you want. 1. Select **Save push rules**. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 4bebe4c1a97..ce3a5ee9916 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,6 +1,6 @@ --- -stage: Systems -group: Gitaly +stage: Create +group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -74,7 +74,7 @@ To purge files from a GitLab repository: 1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell - git clone --bare /path/to/project.bundle + git clone --bare --mirror /path/to/project.bundle ``` 1. Go to the `project.git` directory: @@ -134,6 +134,12 @@ To purge files from a GitLab repository: Repeat this step and all following steps (including the [repository cleanup](#repository-cleanup) step) every time you run any `git filter-repo` command. +1. To allow you to force push the changes you need to unset the mirror flag: + + ```shell + git config --unset remote.origin.mirror + ``` + 1. Force push your changes to overwrite all branches on GitLab: ```shell @@ -160,13 +166,13 @@ To purge files from a GitLab repository: Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. -1. Wait at least 30 minutes, because the repository cleanup process only processes object older than 30 minutes. -1. Run [repository cleanup](#repository-cleanup). +1. Wait at least 30 minutes before attempting the next step. +1. Run [repository cleanup](#repository-cleanup). This process only cleans up objects + that are more than 30 minutes old. See [Space not being freed](#space-not-being-freed) + for more information. ## Repository cleanup -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. - Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a @@ -178,6 +184,10 @@ of the operation. This happens automatically, but submitting the cleanup request fails if any writes are ongoing, so cancel any outstanding `git push` operations before continuing. +WARNING: +Removing internal Git references results in associated merge request commits, pipelines, and changes details +no longer being available. + To clean up a repository: 1. Go to the project for the repository. @@ -300,3 +310,17 @@ end puts "#{artifact_storage} bytes" ``` + +### Space not being freed + +The process defined on this page can decrease the size of repository exports +decreasing, but the usage in the file system appearing unchanged in both the Web UI and terminal. + +The process leaves many unreachable objects remaining in the repository. +Because they are unreachable, they are not included in the export, but they are +still stored in the file system. These files are pruned after a grace period of +two weeks. Pruning deletes these files and ensures your storage usage statistics +are accurate. + +To expedite this process, see the +['Prune Unreachable Objects' housekeeping task](../../../administration/housekeeping.md). diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index f2ce80263c8..8f29845fd9b 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -93,10 +93,10 @@ You can review commits for a merge request, or for an entire project, to confirm they are signed: 1. To review commits for a project: - 1. On the top bar, select **Main menu > Projects** and find your project. - 1. On the left sidebar, select **Repository > Commits**. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Code > Commits**. 1. To review commits for a merge request: - 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Merge requests**, then select your merge request. 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index e252a9a433b..8c6774408e6 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -44,15 +44,15 @@ In the GitLab UI, each tag displays: To view all existing tags for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Tags**. ## View tagged commits in the commits list > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Commits**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Commits**. 1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. This example shows a commit tagged `v1.26.0`: @@ -88,8 +88,8 @@ To create either a lightweight or annotated tag from the command line, and push To create a tag from the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Tags**. 1. Select **New tag**. 1. Provide a **Tag name**. 1. For **Create from**, select an existing branch name, tag, or commit SHA. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index dc988846676..7b2dcd04982 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -25,7 +25,7 @@ for any change you commit through the Web Editor. To create a text file in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. @@ -35,8 +35,8 @@ To create a text file in the Web Editor: ### Create a file from a template -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Files**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Repository**. 1. Next to the project name, select the plus icon (**{plus}**) to display a dropdown list, then select **New file** from the list. 1. For **Filename**, provide one of the filenames that GitLab provides a template for: @@ -56,15 +56,9 @@ To create a text file in the Web Editor: To edit a text file in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Go to your file. -1. In the upper-right corner of the file, select **Edit**. - - If **Edit** is not visible: - - 1. Next to **Open in Web IDE** or **Open in Gitpod**, select the down arrow (**{chevron-lg-down}**). - 1. From the dropdown list, select **Edit** as your default setting. - 1. Select **Edit**. +1. In the upper right, select **Edit > Edit single file**. ### Keyboard shortcuts @@ -111,7 +105,7 @@ To upload a binary file in the Web Editor: <!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> <!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. 1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -121,7 +115,7 @@ To upload a binary file in the Web Editor: To create a directory in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New directory**. 1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. @@ -131,7 +125,7 @@ To create a directory in the Web Editor: To create a [branch](branches/index.md) in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New branch**. 1. Complete the fields. @@ -142,7 +136,7 @@ To create a [branch](branches/index.md) in the Web Editor: You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New tag**. 1. Complete the fields. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index bd5c8214e68..8d525965f96 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -54,11 +54,13 @@ Prerequisites: [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). To do this, you must have administrator access. +- You must have enabled [issue](settings/index.md#configure-project-visibility-features-and-permissions) + tracker for the project. To enable Service Desk in your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Service Desk**. 1. Turn on the **Activate Service Desk** toggle. 1. Optional. Complete the fields. @@ -101,7 +103,8 @@ visible in the email template. For more information, see #### Thank you email -> `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. When a user submits an issue through Service Desk, GitLab sends a **thank you email**. @@ -110,20 +113,23 @@ directory in your repository, create a file named `thank_you.md`. You can use these placeholders to be automatically replaced in each email: -- `%{ISSUE_ID}`: issue IID -- `%{ISSUE_PATH}`: project path appended with the issue IID -- `%{ISSUE_DESCRIPTION}`: issue description based on the original email -- `%{UNSUBSCRIBE_URL}`: unsubscribe URL -- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) +- `%{ISSUE_ID}`: Issue IID. +- `%{ISSUE_PATH}`: Project path appended with the issue IID. +- `%{ISSUE_URL}`: URL to the issue. External participants can only view the issue if the project is public + and issue is not confidential (Service Desk issues are confidential by default). +- `%{ISSUE_DESCRIPTION}`: Issue description based on the original email. +- `%{UNSUBSCRIBE_URL}`: Unsubscribe URL. +- `%{SYSTEM_HEADER}`: [System header message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{SYSTEM_FOOTER}`: [System footer message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{ADDITIONAL_TEXT}`: [Custom additional text](../admin_area/settings/email.md#custom-additional-text). Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), the response email does not contain the issue link. #### New note email -> `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. When a user-submitted issue receives a new comment, GitLab sends a **new note email**. @@ -132,17 +138,19 @@ directory in your repository, create a file named `new_note.md`. You can use these placeholders to be automatically replaced in each email: -- `%{ISSUE_ID}`: issue IID -- `%{ISSUE_PATH}`: project path appended with the issue IID -- `%{ISSUE_DESCRIPTION}`: issue description at the time email is generated. +- `%{ISSUE_ID}`: Issue IID. +- `%{ISSUE_PATH}`: Project path appended with the issue IID. +- `%{ISSUE_URL}`: URL to the issue. External participants can only view the issue if the project is public + and issue is not confidential (Service Desk issues are confidential by default). +- `%{ISSUE_DESCRIPTION}`: Issue description at the time email is generated. If a user has edited the description, it might contain sensitive information that is not intended to be delivered to external participants. Use this placeholder only if you never modify descriptions or your team is aware of the template design. -- `%{NOTE_TEXT}`: note text -- `%{UNSUBSCRIBE_URL}`: unsubscribe URL -- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) -- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) +- `%{NOTE_TEXT}`: Note text. +- `%{UNSUBSCRIBE_URL}`: Unsubscribe URL. +- `%{SYSTEM_HEADER}`: [System header message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{SYSTEM_FOOTER}`: [System footer message](../admin_area/appearance.md#system-header-and-footer-messages). +- `%{ADDITIONAL_TEXT}`: [Custom additional text](../admin_area/settings/email.md#custom-additional-text). ### Use a custom template for Service Desk issues @@ -163,8 +171,8 @@ Prerequisite: To use a custom description template with Service Desk: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Service Desk**. 1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. @@ -174,6 +182,11 @@ Behind the scenes, Service Desk works by the special Support Bot user creating i This user isn't a [billable user](../../subscriptions/self_managed/index.md#billable-users), so it does not count toward the license limit count. +In GitLab 16.0 and earlier, comments generated from Service Desk emails show `GitLab Support Bot` +as the author. In [GitLab 16.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/226995), +these comments show the email of the user who sent the email. +This feature only applies to comments made in GitLab 16.1 and later. + #### Change the Support Bot's display name You can change the display name of the Support Bot user. Emails sent from Service Desk have @@ -181,8 +194,8 @@ this name in the `From` header. The default display name is `GitLab Support Bot` To edit the custom email display name: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Service Desk**. 1. Below **Email display name**, enter a new name. 1. Select **Save changes**. @@ -225,9 +238,10 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip NOTE: In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. -To use `webhook` on an Omnibus installation running GitLab 15.3, you must generate a secret file. +To use `webhook` on a Linux package installation running GitLab 15.3, you must generate a secret file. For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). -In GitLab 15.4, reconfiguring an Omnibus installation generates this secret file automatically, so no secret file configuration setting is needed. +In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no +secret file configuration setting is needed. For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). ```ruby @@ -406,7 +420,7 @@ Service Desk can be configured to read Microsoft Exchange Online mailboxes with Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph [the same way as for incoming email](../../administration/incoming_email.md#microsoft-graph). -- Example for Omnibus GitLab installations: +- Example for Linux package installations: ```ruby gitlab_rails['service_desk_email_enabled'] = true @@ -455,8 +469,8 @@ Prerequisites: - You must have configured a [custom mailbox](#configure-a-custom-mailbox). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Service Desk**. 1. Below **Email address suffix**, enter the suffix to use. 1. Select **Save changes**. @@ -472,6 +486,138 @@ The [incoming email](../../administration/incoming_email.md) address still works If you don't configure a custom suffix, the default project identification is used for identifying the project. +### Configure email ingestion in multi-node environments + +A multi-node environment is a setup where GitLab is run across multiple servers +for scalability, fault tolerance, and performance reasons. + +GitLab uses a separate process called `mail_room` to ingest new unread emails +from the `incoming_email` and `service_desk_email` mailboxes. + +#### Helm chart (Kubernetes) + +The [GitLab Helm chart](https://docs.gitlab.com/charts/) is made up of multiple subcharts, and one of them is +the [Mailroom subchart](https://docs.gitlab.com/charts/charts/gitlab/mailroom/index.html). Configure the +[common settings for `incoming_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#incoming-email-configuration) +and the [common settings for `service_desk_email`](https://docs.gitlab.com/charts/installation/command-line-options.html#service-desk-email-configuration). + +#### Linux package (Omnibus) + +In multi-node Linux package installation environments, run `mail_room` only on one node. Run it either on a single +`rails` node (for example, `application_role`) +or completely separately. + +##### Set up all nodes + +1. Add basic configuration for `incoming_email` and `service_desk_email` on every node + to render email addresses in the web UI and in generated emails. + + Find the `incoming_email` or `service_desk_email` section in `/etc/gitlab/gitlab.rb`: + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_enabled'] = true + gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com" + ``` + + ::EndTabs + +1. GitLab offers two methods to transport emails from `mail_room` to the GitLab +application. You can configure the `delivery_method` for each email setting individually: + 1. Recommended: `webhook` (default in GitLab 15.3 and later) sends the email payload via an API POST request to your GitLab + application. It uses a shared token to authenticate. If you choose this method, + make sure the `mail_room` process can access the API endpoint and distribute the shared + token across all application nodes. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + gitlab_rails['incoming_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + gitlab_rails['service_desk_email_delivery_method'] = "webhook" + + # The URL that mail_room can contact. You can also use an internal URL or IP, + # just make sure mail_room can access the GitLab API via that address. + # Do not end with "/". + + gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com" + + # The shared secret file that should contain a random token. Make sure it's the same on every node. + gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret" + ``` + + ::EndTabs + + 1. [Deprecated in GitLab 16.0 and planned for removal in 17.0)](../../update/deprecations.md#sidekiq-delivery-method-for-incoming_email-and-service_desk_email-is-deprecated): + If you experience issues with the `webhook` setup, use `sidekiq` to deliver the email payload directly to GitLab Sidekiq using Redis. + + ::Tabs + + :::TabTitle `incoming_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['incoming_email_delivery_method'] = "sidekiq" + ``` + + :::TabTitle `service_desk_email` + + ```ruby + # It uses the Redis configuration to directly add Sidekiq jobs + gitlab_rails['service_desk_email_delivery_method'] = "sidekiq" + ``` + + ::EndTabs + +1. Disable `mail_room` on all nodes that should not run email ingestion. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = false + ``` + +1. [Reconfigure GitLab](../../administration/restart_gitlab.md) for the changes to take effect. + +##### Set up a single email ingestion node + +After setting up all nodes and disabling the `mail_room` process, enable `mail_room` on a single node. +This node polls the mailboxes for `incoming_email` and `service_desk_email` on a regular basis and +move new unread emails to GitLab. + +1. Choose an existing node that additionally handles email ingestion. +1. Add [full configuration and credentials](../../administration/incoming_email.md#configuration-examples) + for `incoming_email` and `service_desk_email`. +1. Enable `mail_room` on this node. For example, in `/etc/gitlab/gitlab.rb`: + + ```ruby + mailroom['enabled'] = true + ``` + +1. [Reconfigure GitLab](../../administration/restart_gitlab.md) on this node for the changes to take effect. + ## Use Service Desk You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). @@ -481,8 +627,8 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo To check what the Service Desk email address is for your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Service Desk**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Monitor > Service Desk**. The email address is available at the top of the issue list. @@ -533,8 +679,8 @@ Prerequisites: To view Service Desk issues: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues > Service Desk**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Monitor > Service Desk**. ### Email contents and formatting @@ -570,7 +716,7 @@ In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. Service Desk issues are [confidential](issues/confidential_issues.md), so they are only visible to project members. The project owner can -[make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). +[make an issue public](issues/confidential_issues.md#in-an-existing-issue). When a Service Desk issue becomes public, the issue creator's and participants' email addresses are visible to signed-in users with at least the Reporter role for the project. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 958246908bc..6cc2b51f077 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -86,8 +86,9 @@ Before you can migrate projects on a self-managed GitLab instance using file exp To enable file exports as an import source for the destination instance: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. 1. Select the **GitLab export** checkbox. @@ -112,8 +113,8 @@ Prerequisites: To export a project and its data, follow these steps: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Export project**. 1. After the export is generated, you should receive an email with a link to download the file. @@ -181,6 +182,8 @@ Items that are **not** exported include: - Secure files - [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700) (for example, pushing and creating tags) - Security policies associated with your project +- Links between issues and linked items +- Links to related merge requests Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and [instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index f89c2a1eaaa..8deb05c45ef 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -13,8 +13,8 @@ Use the **Settings** page to manage the configuration options in your [project]( You must have at least the Maintainer role to view project settings. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. To display all settings in a section, select **Expand**. 1. Optional. Use the search box to find a setting. @@ -23,8 +23,8 @@ You must have at least the Maintainer role to view project settings. Use the project general settings to edit your project details. 1. Sign in to GitLab with at least the Maintainer role. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. In the **Project name** text box, enter your project name. 1. In the **Project description** text box, enter your project description. 1. Under **Project avatar**, to change your project avatar, select **Choose file**. @@ -35,8 +35,8 @@ Use topics to categorize projects and find similar new projects. To assign topics to a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings** > **General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings** > **General**. 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. @@ -49,9 +49,9 @@ If you're an instance administrator, you can administer all project topics from compliance framework using either: - The GitLab UI: - 1. On the top bar, select **Main menu > Projects > View all projects** and find your project. - 1. On the left sidebar, select **Settings** > **General**. - 1. Expand the **Compliance frameworks** section. + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings** > **General**. + 1. Expand **Compliance frameworks**. 1. Select a compliance framework. 1. Select **Save changes**. - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the @@ -59,13 +59,16 @@ compliance framework using either: compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user has the correct permissions. The GitLab UI presents a read-only view to discourage this behavior. +NOTE: +Frameworks can not be added to projects in personal namespaces. + ## Configure project visibility, features, and permissions To configure visibility, features, and permissions for a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. To change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. 1. To allow users to request access to the project, select the **Users can request access** checkbox. 1. Use the [toggles](#project-feature-settings) to enable or disable features in the project. @@ -130,9 +133,9 @@ In some environments, users can submit a [CVE identifier request](../../applicat To disable the CVE identifier request option in issues in your project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. 1. Select **Save changes**. @@ -142,9 +145,9 @@ Prerequisites: - You must be an Owner of the project to disable email notifications related to the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility, project features, permissions** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Clear the **Disable email notifications** checkbox. ## Configure merge request settings for a project @@ -156,7 +159,7 @@ Configure your project's merge request settings: - Enable [merge request approvals](../merge_requests/approvals/index.md). - Enable [status checks](../merge_requests/status_checks.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). +- Enable [merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). @@ -184,8 +187,8 @@ other features are read-only. Archived projects are also hidden from project lis To archive a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Archive project** section, select **Archive project**. 1. To confirm, select **OK**. @@ -200,7 +203,8 @@ Prerequisites: - To unarchive a project, you must be an administrator or a project Owner. 1. Find the archived project. - 1. On the top bar, select **Main menu > Projects > View all projects**. + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **View all your projects**. 1. Select **Explore projects**. 1. In the **Sort projects** dropdown list, select **Show archived projects**. 1. In the **Filter by name** field, enter the project name. @@ -225,9 +229,9 @@ When you change the repository path, users may experience issues if they push to To rename a repository: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Advanced** section. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. 1. In the **Change path** text box, edit the path. 1. Select **Change path**. @@ -238,8 +242,8 @@ In merge requests, you can change the default behavior so that the To set this default: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Merge requests**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Merge requests**. 1. Select **Enable "Delete source branch" option by default**. 1. Select **Save changes**. @@ -249,7 +253,7 @@ When you transfer a project to another namespace, you move the project to a diff Prerequisites: -- You must have at least the Maintainer role for the [group](../../group/manage.md#create-a-group) to which you are transferring. +- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) to which you are transferring. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). @@ -258,8 +262,8 @@ Prerequisites: To transfer a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Under **Transfer project**, choose the namespace to transfer the project to. 1. Select **Transfer project**. @@ -281,6 +285,11 @@ When you transfer a project from a namespace licensed for GitLab SaaS Premium or ## Delete a project +> - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. +> - Default deletion behavior for projects changed to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. +> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. + You can mark a project to be deleted. Prerequisite: @@ -289,37 +298,34 @@ Prerequisite: To delete a project: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. -1. In the "Delete project" section, select **Delete project**. -1. Confirm the action when asked to. +1. In the **Delete this project** section, select **Delete project**. +1. In the confirmation message text field, enter the name of the project as instructed, and select **Yes, delete project**. -This action deletes a project including all associated resources (such as issues and merge requests). - -WARNING: -The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) -in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +This action deletes the project and all associated resources (such as issues and merge requests). ### Delayed project deletion **(PREMIUM)** > - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. > - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. +> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. -Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether -delayed project deletion is enabled for a particular project: +Projects in a group (not a personal namespace) can be deleted after a delay period. -- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#delayed-project-deletion). - You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the - delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). -- Group [settings](../../group/manage.md#enable-delayed-project-deletion) to enabled delayed project deletion for all - projects in the group. +On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. +On SaaS, there is a non-adjustable default retention period of seven days. ### Delete a project immediately -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. +> - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. + +If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again. -If you don't want to wait, you can delete a project immediately. +In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. +If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately. Prerequisites: @@ -328,16 +334,11 @@ Prerequisites: To immediately delete a project marked for deletion: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Advanced**. -1. In the "Permanently delete project" section, select **Delete project**. -1. Confirm the action when asked to. - -The following are deleted: - -- Your project and its repository. -- All related resources including issues and merge requests. +1. In the **Delete this project** section, select **Delete project**. +1. In the confirmation message text field, enter the name of the project as instructed, as select **Yes, delete project**. ## Restore a project **(PREMIUM)** @@ -345,7 +346,9 @@ The following are deleted: To restore a project marked for deletion: -1. Navigate to your project, and select **Settings > General > Advanced**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. 1. In the Restore project section, select **Restore project**. ## Monitor settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 178500093e2..7fd8fdf3a00 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -11,6 +11,7 @@ type: reference, howto > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. +> - [Became available in trial subscriptions](https://gitlab.com/gitlab-org/gitlab/-/issues/386041) in GitLab 16.1. Default prefix added. Project access tokens are similar to passwords, except you can [limit access to resources](#scopes-for-a-project-access-token), select a limited role, and provide an expiry date. @@ -32,12 +33,9 @@ The ability to create project access tokens without expiry was [deprecated](http You can use project access tokens: -- On GitLab SaaS: If you have the Premium or Ultimate license tier. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). -- On self-managed instances of GitLab: With any license tier. If you have the Free tier: - - Review your security and compliance policies around - [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). - - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to - lower potential abuse. +- On GitLab SaaS: If you have the Premium or Ultimate license tier, only one project access token is available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab: With any license tier. If you have the Free tier, + consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. You cannot use project access tokens to create other group, project, or personal access tokens. @@ -57,8 +55,8 @@ all projects that have visibility level set to [Internal](../../public_access.md To create a project access token: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Access Tokens**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Enter an expiry date for the token. - The token expires on that date at midnight UTC. @@ -75,8 +73,8 @@ A project access token is displayed. Save the project access token somewhere saf To revoke a project access token: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Access Tokens**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Access Tokens**. 1. Next to the project access token to revoke, select **Revoke**. ## Scopes for a project access token @@ -98,8 +96,8 @@ The scope determines the actions you can perform when you authenticate with a pr To enable or disable project access token creation for all projects in a top-level group: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Allow project and group access token creation**. @@ -112,7 +110,7 @@ Even when creation is disabled, you can still use and revoke existing project ac Bot users for projects are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). Each time you create a project access token, a bot user is created and added to the project. -These bot users do not count as licensed seats. +This user is not a billable user, so it does not count toward the license limit. The bot users for projects have [permissions](../../permissions.md#project-members-permissions) that correspond with the selected role and [scope](#scopes-for-a-project-access-token) of the project access token. @@ -139,4 +137,4 @@ See also [Bot users for groups](../../group/settings/group_access_tokens.md#bot- ## Token availability -Project access tokens are only available in paid subscriptions, and not available in trial subscriptions. For more information, see the ["What is included" section of the GitLab Trial FAQ](https://about.gitlab.com/free-trial/#what-is-included-in-my-free-trial-what-is-excluded). +More than one project access token is only available in paid subscriptions. In Premium and Ultimate trial subscriptions, only one project access token is included. For more information, see the ["What is included" section of the GitLab Trial FAQ](https://about.gitlab.com/free-trial/#what-is-included-in-my-free-trial-what-is-excluded). diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 1eee4364d95..56873c328fa 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -31,23 +31,23 @@ The filtering options are: ### On an epic -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Epics** (**{epic}**). +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Epics**. 1. Identify your desired epic, and select its title. 1. Go to the **Activity** section. 1. For **Sort or filter**, select **Show all activity**. ### On an issue -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Issues** and find your issue. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Issues** and find your issue. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. ### On a merge request -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Code > Merge requests** and find your merge request. 1. Go to **Activity**. 1. For **Sort or filter**, select **Show all activity**. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index bd935db6f02..9b5469f6cec 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -185,8 +185,8 @@ The following time units are available: In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index bb1609a74e5..481eca5a890 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -23,7 +23,7 @@ To pair the Web IDE with a remote development environment, see [remote developme To open the Web IDE from the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Use the <kbd>.</kbd> keyboard shortcut. You can also open the Web IDE from: @@ -36,13 +36,7 @@ You can also open the Web IDE from: To open the Web IDE from a file or the repository file list: -- In the upper-right corner of the page, select **Open in Web IDE**. - -If **Open in Web IDE** is not visible: - -1. Next to **Edit** or **Gitpod**, select the down arrow (**{chevron-lg-down}**). -1. From the dropdown list, select **Open in Web IDE**. -1. Select **Open in Web IDE**. +- In the upper right, select **Edit > Open in Web IDE**. ### From a merge request @@ -89,17 +83,17 @@ For more information, see the [VS Code documentation](https://code.visualstudio. ## Upload a new file -To upload a new file and add it to the Git repository: +To upload a new file in the Web IDE: -1. In the **Explorer** file tree, navigate to the directory where you want to upload the file. -1. Optional. If the directory does not exist yet, select the directory path where you want to have a new directory and either: - - Right-click on the directory path, and select **New Folder...**. You can create a nested directory path with the `/` separator, for example `parentdir/subdir1/subdir2`. - - In the **Explorer** panel, in the upper-right corner, select the new folder (**{folder-new}**) icon. -1. Enter the name of the new directory, and press <kbd>Enter/Return</kbd> to create it. -1. Right-click on the directory path and select `Upload...`. -1. Select the file you want to upload, then select `Open`. You can select and add multiple files at once. +1. On the activity bar on the left, select **Explorer** and go to the directory where you want to upload the file. +1. Optional. For a new directory, go to the path where you want to have the directory and do one of the following: + - Right-click the path, and select **New Folder...**. You can create a nested path with `/` (for example, `parentdir/subdir1/subdir2`). + - In the upper right of the **Explorer** panel, select **New Folder...** (**{folder-new}**). +1. Enter the name of the new directory, and press <kbd>Enter</kbd>. +1. Right-click the path, and select **Upload...**. +1. Select the file you want to upload, then select **Open**. You can upload multiple files at once. -The file is uploaded and automatically added as a new file to the Git repository. +The new file is uploaded and automatically added to the repository. ## Switch branches @@ -129,7 +123,17 @@ To commit changes in the Web IDE: or press <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>. 1. Enter your commit message. 1. Select **Commit & Push**. -1. Commit to the current branch, or create a new branch. +1. Commit to the current branch, or [create a new branch](#create-a-branch). + +## Create a merge request + +To create a merge request in the Web IDE: + +1. [Commit the changes](#commit-changes). +1. In the pop-up notification in the lower-right corner, select **Create Merge Request**. + A new window opens for you to create the [merge request](../merge_requests/index.md). + +To access missed notifications, see [Access notifications](#access-notifications). ## Use the command palette @@ -178,6 +182,13 @@ To change the Web IDE theme: The active color theme is stored in the [user settings](#edit-settings). +## Access notifications + +When you perform actions in the Web IDE, notifications appear in the lower-right corner. To access missed notifications: + +1. On the status bar, in the lower-right corner, select the bell (**{notifications}**) for a list of notifications. +1. Select the notification you want to access. + <!-- ## Privacy and data collection for extensions The Web IDE Extension Marketplace is based on Open VSX. Open VSX does not collect any @@ -194,6 +205,9 @@ To protect your privacy and data: ## Interactive web terminals for the Web IDE (Beta) +WARNING: +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. + When you set up a remote development server in the Web IDE, you can use interactive web terminals to: - Access a remote shell on the server. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 9327ce53b3f..2271c33b5b4 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -27,10 +27,10 @@ can edit group wikis. Group wiki repositories can be moved using the To access a group wiki: -1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. To display the wiki, either: - - On the left sidebar, select **Wiki**. - - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + - On the left sidebar, select **Plan > Wiki**. + - On any page in the group, use the <kbd>g</kbd> + <kbd>w</kbd> [wiki keyboard shortcut](../../shortcuts.md). ## Export a group wiki @@ -67,8 +67,8 @@ can enable or disable a group wiki through the group settings. To open group settings: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: - **Enabled**: For public groups, everyone can access the wiki. For internal groups, only authenticated users can access the wiki. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index eb13814f2ad..0d3782cfd09 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -31,9 +31,9 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se To access a project wiki: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. To display the wiki, either: - - On the left sidebar, select **Wiki**. + - On the left sidebar, select **Plan > Wiki**. - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> [wiki keyboard shortcut](../../shortcuts.md). @@ -61,10 +61,8 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Select **Create your first page**. 1. GitLab requires this first page be titled `home`. The page with this title serves as the front page for your wiki. @@ -79,10 +77,8 @@ to be used as your wiki's home page. To create it: Users with at least the Developer role can create new wiki pages: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. 1. Add a title for your new page. Page titles use @@ -142,10 +138,8 @@ may not be able to check out the wiki locally afterward. You need at least the Developer role to edit a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to edit, and either: - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). - Select the edit icon (**{pencil}**). @@ -163,10 +157,8 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the Developer role to delete a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to delete. 1. Select the edit icon (**{pencil}**). 1. Select **Delete page**. @@ -176,10 +168,8 @@ You need at least the Developer role to delete a wiki page: You need at least the Developer role to move a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. For example, if you have a wiki page @@ -202,10 +192,8 @@ The history page shows: To view the changes for a wiki page: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the page you want to view history for. 1. Select **Page history**. @@ -215,10 +203,8 @@ To view the changes for a wiki page: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in. @@ -248,10 +234,8 @@ You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. On the top bar, select **Main menu**. - - For project wikis, select **Projects** and find your project. - - For group wikis, select **Groups** and find your group. -1. On the left sidebar, select **Wiki**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Plan > Wiki**. 1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -284,11 +268,11 @@ You can disable group wikis from the [group settings](group.md#configure-group-w To add a link to an external wiki from a project's left sidebar: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. -1. Optional. To verify the connection, select **Test settings**. +1. Optional. Select **Test settings**. 1. Select **Save changes**. You can now see the **External wiki** option from your project's @@ -300,8 +284,8 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. 1. Select **External wiki**. 1. In the **Enable integration** section, clear the **Active** checkbox. 1. Select **Save changes**. @@ -310,8 +294,8 @@ To hide the link to an external wiki: To disable a project's internal wiki: -1. On the top bar, select **Main menu > Projects** and find your project. -1. Go to your project and select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). 1. Select **Save changes**. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 69087791a3e..5bd7c12ed31 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -11,9 +11,15 @@ code are saved in projects, and most features are in the scope of projects. ## View projects -To view all your projects, on the top bar, select **Main menu > Projects > View all projects**. +To view all your projects: -To browse all public projects, select **Main menu > Explore > Projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. + +To browse all projects you can access: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Explore**. ### Who can view the Projects page @@ -42,11 +48,12 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec To explore project topics: -1. On the top bar, select **Main menu > Projects > View all projects**. -1. Select the **Explore topics** tab. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Explore**. +1. On the left sidebar, select **Topics**. 1. To view projects associated with a topic, select a topic. -The **Explore topics** tab shows a list of topics sorted by the number of associated projects. +The **Explore topics** page shows a list of topics, sorted by the number of associated projects. You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). @@ -59,13 +66,14 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. In the upper-right corner of the page, select **Star**. ## View starred projects -1. On the top bar, select **Main menu > Projects > View all projects**. -1. Select the **Starred projects** tab. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. +1. Select the **Starred** tab. 1. GitLab displays information about your starred projects, including: - Project description, including name, description, and icon. @@ -83,17 +91,20 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: -1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. In the **Yours** tab, select **Personal**. ## Delete a project -After you delete a project, projects in personal namespaces are deleted immediately. To delay deletion of projects in a group -you can [enable delayed project removal](../group/manage.md#enable-delayed-project-deletion). +After you delete a project: + +- Projects in personal namespaces are deleted immediately. +- Projects in groups are [deleted after a retention period](../project/settings/index.md#delayed-project-deletion). To delete a project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. @@ -107,12 +118,10 @@ To delete a project: > - [Available to all users](https://gitlab.com/gitlab-org/gitlab/-/issues/346976) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) in GitLab 14.9. [Feature flag `project_owners_list_project_pending_deletion`](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) removed. -When delayed project deletion is [enabled for a group](../group/manage.md#enable-delayed-project-deletion), -projects within that group are not deleted immediately, but only after a delay. - To view a list of all projects that are pending deletion: -1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **View all your projects**. 1. Based on your GitLab version: - GitLab 14.6 and later: select the **Pending deletion** tab. - GitLab 14.5 and earlier: select the **Deleted projects** tab. @@ -127,18 +136,14 @@ Each project in the list shows: To view the activity of a project: -1. On the top bar, select **Main menu > Projects** and find your project.. -1. On the left sidebar, select **Project information > Activity**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Manage > Activity**. 1. Select a tab to view the type of project activity. ## Search in projects -You can search through your projects. - -1. On the top bar, select **Main menu**. -1. In **Search your projects**, type the project name. - -GitLab filters as you type. +To search through your projects, on the left sidebar, at the top, select **Search GitLab** +(**{search}**). GitLab filters as you type. You can also look for the projects you [starred](#star-a-project) (**Starred projects**). @@ -161,7 +166,10 @@ You can also choose to hide or show archived projects. You can filter projects by the programming language they use. To do this: -1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select either: + - **View all your projects**, to filter your projects. + - **Explore**, to filter all projects you can access. 1. From the **Language** dropdown list, select the language you want to filter projects by. A list of projects that use the selected language is displayed. @@ -174,8 +182,8 @@ Prerequisite: - You must have the Owner role for the project. -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggle by each feature you want to turn on or off, or change access for. 1. Select **Save changes**. @@ -190,7 +198,7 @@ When you leave a project: To leave a project: -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a [group namespace](../namespace/index.md). |