diff options
Diffstat (limited to 'doc/user/project')
136 files changed, 1601 insertions, 1072 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 2f9e04fb828..cf0ff4ed8b9 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -21,7 +21,7 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. On the top bar, select **Menu > Projects** and find 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 **Badges**. 1. Under "Link", enter the URL that the badges should point to and under @@ -41,7 +41,7 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. On the top bar, select **Menu > Projects** and find 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 **Badges**. 1. Under **Name**, enter _Pipeline Status_. @@ -68,7 +68,7 @@ If you need individual badges for each project, either: To add a new badge to a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under @@ -118,7 +118,7 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge to a group or project with a custom image: -1. On the top bar, select **Menu** and find your 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. Expand **Badges**. 1. Under **Name**, enter the name for the badge. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index f8494116655..aac704e2cdd 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -38,8 +38,8 @@ want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you -may want to consider -[setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), +may want to consider +[setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of this document. ## Advanced traffic control with Canary Ingress diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index be73f2c9a01..d9339291328 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -56,7 +56,7 @@ cluster certificates: 1. Go to your: - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Menu > Admin > Kubernetes**, for an instance-level cluster. + - **Main menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -248,7 +248,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. In GitLab, on the top bar, select **Menu > Admin > Settings > General** and expand the **Amazon EKS** section. +1. In GitLab, on the top bar, select **Main menu > Admin > Settings > General** and expand the **Amazon EKS** section. 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/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index c55c11151ce..d7137c18a03 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -68,7 +68,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Menu > Admin > Kubernetes** page, for an instance-level cluster. + 1. **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown menu. 1. On the **Connect a cluster** page, fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index bfaf9aab7b7..6ed02838e9b 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -51,7 +51,7 @@ Note the following: cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to - set up an [initial service account](cluster_access.md). In + set up an [initial service account](cluster_access.md). In [GitLab versions 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process explicitly requests GKE to create clusters with basic authentication enabled and a client certificate. @@ -63,7 +63,7 @@ cluster certificates: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu > Admin > Kubernetes** page, for an instance-level cluster. + - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index f1004a40a13..2fba00ae940 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -19,7 +19,7 @@ When you successfully connect an existing cluster using cluster certificates, th 1. Go to your: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu > Admin > Kubernetes** page, for an instance-level cluster. + - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). 1. Select **Save changes**. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index f89d863e83b..940b58103f5 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 7f35caf2a68..860ebfbed14 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -17,7 +17,10 @@ development environments (IDE), including: Code Intelligence is built into GitLab and powered by [LSIF](https://lsif.dev/) (Language Server Index Format), a file format for precomputed code -intelligence data. +intelligence data. GitLab processes one LSIF file per project, and +Code Intelligence does not support different LSIF files per branch. +Follow epic [#4212, Code intelligence enhancements](https://gitlab.com/groups/gitlab-org/-/epics/4212) +for progress on upcoming enhancements. NOTE: You can automate this feature in your applications by using [Auto DevOps](../../topics/autodevops/index.md). @@ -59,13 +62,5 @@ under the **References** tab: ## Language support Generating an LSIF file requires a language server indexer implementation for the -relevant language. - -| Language | Implementation | -|---|---| -| Go | [`sourcegraph/lsif-go`](https://github.com/sourcegraph/lsif-go) | -| JavaScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | -| TypeScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | - -View a complete list of [available LSIF indexers](https://lsif.dev/#implementations-server) on their website and +relevant language. View a complete list of [available LSIF indexers](https://lsif.dev/#implementations-server) on their website and refer to their documentation to see how to generate an LSIF file for your specific language. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 41afbdada6b..63010610605 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -116,7 +116,7 @@ To display the deploy boards for a specific [environment](../../ci/environments/ Kubernetes. NOTE: - Matching based on the Kubernetes `app` label was removed in + Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). To migrate, please apply the required annotations (see above) and re-deploy your application. If you are using Auto DevOps, this will diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index a9f19d27416..f424ec529b2 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -54,7 +54,7 @@ For example: To view the deploy keys available to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. @@ -72,7 +72,7 @@ Prerequisites: - [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH key on the host that requires access to the repository. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Complete the fields. @@ -92,7 +92,7 @@ Prerequisites: To create a public deploy key: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. 1. Complete the fields. @@ -109,7 +109,7 @@ Prerequisites: To grant a public deploy key access to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Publicly accessible deploy keys**. @@ -129,7 +129,7 @@ Prerequisites: To disable a deploy key: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 595f5e541b7..04a2eeacffb 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -31,7 +31,7 @@ You can create as many deploy tokens as you need from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). 1. Sign in to your GitLab account. -1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** to find your project or group. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. Choose a name, and optionally, an expiration date and username for the token. @@ -51,7 +51,7 @@ Deploy tokens expire at midnight UTC on the date you define. To revoke a deploy token: -1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** to find your project or group. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy tokens**. 1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. @@ -190,7 +190,8 @@ To pull images from the Dependency Proxy, you must: ### GitLab deploy token -> Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. +> - Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. +> - [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4. There's a special case when it comes to deploy tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the deploy token is diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 5df3a973cca..4050fa34026 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -32,7 +32,7 @@ directory in your repository. To create an issue description template: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -51,7 +51,7 @@ push to your default branch. To create a merge request description template: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository**. 1. Next to the default branch, select **{plus}**. 1. Select **New file**. @@ -103,7 +103,7 @@ As a result, you can use the same templates in issues and merge requests in all To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Templates**. 1. From the dropdown list, select your template project as the template repository at group level. @@ -134,10 +134,9 @@ 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 higher: set the default template in project settings: - 1. On the top bar, select **Menu > Projects** and find your project. - 1. On the left sidebar, select **Settings**. - 1. Expand **Merge requests**. - 1. Fill in the **Default description template for merge requests** text area. + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Merge requests**. + 1. In the **Merge commit message template** section, fill in **Default description template for merge requests**. 1. Select **Save changes**. To set a default description template for issues, either: @@ -147,7 +146,7 @@ To set a default description template for issues, either: This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and higher: set the default template in project settings: - 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings**. 1. Expand **Default issue template**. 1. Fill in the **Default description template for issues** text area. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 4810fb96ed3..f1b9bde6cd0 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -220,7 +220,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Locked Files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 90f64b7262c..f2e4b65e3d4 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -23,5 +23,5 @@ ignored. ## Syntax Highlighting The `.gitattributes` file can be used to define which language to use when -syntax highlighting files and diffs. See +syntax highlighting files and diffs. See ["Syntax Highlighting"](highlighting.md) for more information. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index d9ad0c57d79..2d9f92c38e4 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w tools developed by IBM which also include a centralized version control system similar to Git. -A good read of ClearCase's basic concepts is can be found in this +A good read of ClearCase's basic concepts is can be found in this [StackOverflow post](https://stackoverflow.com/a/645771/974710). The following table illustrates the main differences between ClearCase and Git: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index a3dfa3edff0..c04f734e8bb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,7 +26,7 @@ If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#allowlist-for-local-requests) +- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). @@ -62,7 +62,7 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) that matches their GitLab account's email address. GitLab content imports that use GitHub accounts require that the GitHub public-facing email address is populated. This means @@ -76,7 +76,7 @@ field to be populated so you may have to add it on existing accounts. Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: - A GitLab account that has logged in using the GitHub icon. -- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/reference/users#get-a-user) in the profile of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) in the profile of the GitHub user If you are importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). We do not recommend this method, as it does not associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -171,12 +171,15 @@ The following items of a project are imported: - Repository description. - Git repository data. +- Branch protection rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22650) in GitLab 15.4. - Issues. - Pull requests. - Wiki pages. - Milestones. - Labels. - Release note descriptions. +- Release note attachments. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4 with `github_importer_attachments_import` + [feature flag](../../../administration/feature_flags.md) disabled by default. - Pull request review comments. - Regular issue and pull request comments. - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md). @@ -184,6 +187,8 @@ The following items of a project are imported: - Pull request "merged by" information (GitLab.com and GitLab 13.7 and later). - Pull request comments replies in discussions ([GitLab.com and GitLab 14.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)). - Diff Notes suggestions ([GitLab.com and GitLab 14.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)). +- Issue events and pull requests events. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7673) in GitLab 15.4 with `github_importer_issue_events_import` + [feature flag](../../../administration/feature_flags.md) disabled by default. References to pull requests and issues are preserved. Each imported repository maintains visibility level unless that [visibility level is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), in which case it diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 4103367accc..8d30a9c7f52 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,29 +5,30 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project importing from GitLab.com to your private GitLab instance **(FREE)** +# Import a project from GitLab.com to your private GitLab instance **(FREE)** -You can import your existing GitLab.com projects to your GitLab instance, but keep in -mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. -[Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). +You can import your existing GitLab.com projects to your GitLab instance. -To get to the importer page you need to go to "New project" page. +Prerequisite: -NOTE: -If you are interested in importing Wiki and merge request data to your new instance, -you'll need to follow the instructions for [exporting a project](../settings/import_export.md#export-a-project-and-its-data) +- GitLab.com integration must be enabled on your GitLab instance. + [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). - +To import a GitLab.com project to your self-managed GitLab instance: -Go to the **Import Projects** tab, then select **GitLab.com**, and you are redirected to GitLab.com -for permission to access your projects. After accepting, you are automatically redirected to the importer. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Import project**. +1. Select **GitLab.com**. +1. Give GitLab.com permission to access your projects. +1. Select **Import**. - +The importer imports your repository and issues. +When the importer is done, a new GitLab project is created with your imported data. -To import a project, select **Import**. The importer imports your repository and issues. -Once the importer is done, a new GitLab project is created with your imported data. +## Related topics -## Automate group and project import **(PREMIUM)** - -For information on automating user, group, and project import API calls, see -[Automate group and project import](index.md#automate-group-and-project-import). +- To automate user, group, and project import API calls, see + [Automate group and project import](index.md#automate-group-and-project-import). +- To import Wiki and merge request data to your new instance, + see [exporting a project](../settings/import_export.md#export-a-project-and-its-data). diff --git a/doc/user/project/import/img/gitlab_importer.png b/doc/user/project/import/img/gitlab_importer.png Binary files differdeleted file mode 100644 index 27d42eb492e..00000000000 --- a/doc/user/project/import/img/gitlab_importer.png +++ /dev/null diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png Binary files differdeleted file mode 100644 index ff6e5dbf4a1..00000000000 --- a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 432f043f945..72d533efd1b 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -85,7 +85,7 @@ Migrate the assets in this order: Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). -You must still migrate your [Container Registry](../../packages/container_registry/) +You must still migrate your [Container Registry](../../packages/container_registry/index.md) over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. ## Migrate from GitLab.com to self-managed GitLab @@ -142,5 +142,10 @@ GitLab from: - Bitbucket Server - Bitbucket Data Center -See the [Quick Start Guide](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start) -to learn how to use this approach for migrating users, groups, and projects at scale. +For more information, see: + +- [Quick Start](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start). +- [Frequently Asked Migration Questions](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/customer/famq.md), + including settings that need checking afterwards and other limitations. + +For support, customers must enter into a paid engagement with GitLab Professional Services. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5163f957171..d64bea2bb41 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -1. On the top bar, select **Menu > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. 1. Enter a **Git repository URL**. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index b88abf91ae1..d6bcb0a2018 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -5,186 +5,87 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from SVN to GitLab **(FREE)** +# Migrate from Subversion to GitLab **(FREE)** -Subversion (SVN) is a central version control system (VCS) while -Git is a distributed version control system. There are some major differences -between the two, for more information consult your favorite search engine. +GitLab uses Git as its version control system. If you're using Subversion (SVN) as your version control system, +you can migrate to using a Git repository in GitLab using `svn2git`. -There are two approaches to SVN to Git migration: +You can follow the steps on this page to migrate to Git if your SVN repository: -- [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: - - Makes the GitLab repository to mirror the SVN project. - - Git and SVN repositories are kept in sync; you can use either one. - - Smoothens the migration process and allows you to manage migration risks. +- Has a standard format (trunk, branches, and tags). +- Is not nested. -- [Cut over migration](#cut-over-migration-with-svn2git) which: - - Translates and imports the existing data and history from SVN to Git. - - Is a fire and forget approach, good for smaller teams. +For a non-standard repository see the [`svn2git` documentation](https://github.com/nirvdrum/svn2git). -## Smooth migration with a Git/SVN mirror using SubGit +We recommend a hard cut over from SVN to Git and GitLab. Run the migration command once and then have all users use the +new GitLab repository immediately. -[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git -migration. It creates a writable Git mirror of a local or remote Subversion -repository and that way you can use both Subversion and Git as long as you like. -It requires access to your GitLab server as it talks with the Git repositories -directly in a file system level. +## Install `svn2git` -### SubGit prerequisites +Install `svn2git` on a local workstation rather than the GitLab server: -1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can - follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). -1. Download SubGit from <https://subgit.com/download>. -1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` - command is available at `/opt/subgit-VERSION/bin/subgit`. +- On all systems you can install as a Ruby gem if you already have Ruby and Git installed: -### SubGit configuration + ```shell + sudo gem install svn2git + ``` -The first step to mirror you SVN repository in GitLab is to create a new empty -project that is used as a mirror. For Omnibus installations the path to -the repository is -`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For -installations from source, the default repository directory is -`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a -variable: +- On Debian-based Linux distributions you can install the native packages: -```shell -GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git -``` + ```shell + sudo apt-get install git-core git-svn ruby + ``` -SubGit keeps this repository in sync with a remote SVN project. For -convenience, assign your remote SVN project URL to a variable: +## Prepare an authors file (recommended) -```shell -SVN_PROJECT_URL=http://svn.company.com/repos/project -``` +Prepare an authors file so `svn2git` can map SVN authors to Git authors. If you choose not to create the authors file, +commits are not attributed to the correct GitLab user. -Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following -`subgit` command is ran on behalf of the same user that keeps ownership of -GitLab Git repositories (by default `git`): +To map authors, you must map every author present on changes in the SVN repository. If you don't, the +migration fails and you have to update the author file accordingly. -```shell -subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH -``` +1. Search through the SVN repository and output a list of authors: -Adjust authors and branches mappings, if necessary. Open with your favorite -text editor: + ```shell + svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq + ``` -```shell -edit $GIT_REPO_PATH/subgit/authors.txt -edit $GIT_REPO_PATH/subgit/config -``` +1. Use the output from the last command to construct the authors file. Create a file called `authors.txt` and add one + mapping per line. For example: -For more information regarding the SubGit configuration options, refer to -[SubGit's documentation](https://subgit.com/documentation/) website. + ```plaintext + sidneyjones = Sidney Jones <sidneyjones@example.com> + ``` -### Initial translation +## Migrate SVN repository to Git repository -Now that SubGit has configured the Git/SVN repositories, run `subgit` to perform the -initial translation of existing SVN revisions into the Git repository: +`svn2git` supports excluding certain file paths, branches, tags, and more. See +the [`svn2git` documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of +the available options. -```shell -subgit install $GIT_REPO_PATH -``` +For each repository to migrate: -After the initial translation is completed, `subgit` keeps the Git repository and the SVN -project sync - new Git commits are translated to -SVN revisions and new SVN revisions are translated to Git commits. Mirror -works transparently and does not require any special commands. +1. Create a new directory and change into it. +1. For repositories that: -If you would prefer to perform one-time cut over migration with `subgit`, use -the `import` command instead of `install`: + - Don't require a username and password, run: -```shell -subgit import $GIT_REPO_PATH -``` + ```shell + svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt + ``` -### SubGit licensing + - Do require a username and password, run: -Running SubGit in a mirror mode requires a -[registration](https://subgit.com/pricing). Registration is free for open -source, academic and startup projects. + ```shell + svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt --username <username> --password <password> + ``` -### SubGit support +1. Create a new GitLab project for your migrated code. +1. Copy the SSH or HTTP(S) repository URL from the GitLab project page. +1. Add the GitLab repository as a Git remote and push all the changes. This pushes all commits, branches, and tags. -For any questions related to SVN to GitLab migration with SubGit, you can -contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com). - -## Cut over migration with svn2git - -NOTE: -Any issues with svn2git should be directed to the [relevant project and maintainer](https://github.com/nirvdrum/svn2git). -Check for existing issues and history for update frequency. - -If you are currently using an SVN repository, you can migrate the repository -to Git and GitLab. We recommend a hard cut over - run the migration command once -and then have all developers start using the new GitLab repository immediately. -Otherwise, it's hard to keep changing in sync in both directions. The conversion -process should be run on a local workstation. - -Install `svn2git`. On all systems you can install as a Ruby gem if you already -have Ruby and Git installed. - -```shell -sudo gem install svn2git -``` - -On Debian-based Linux distributions you can install the native packages: - -```shell -sudo apt-get install git-core git-svn ruby -``` - -Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. -If you choose not to create the authors file then commits are not attributed -to the correct GitLab user. Some users may not consider this a big issue while -others want to ensure they complete this step. If you choose to map authors, -you must map every author present on changes in the SVN -repository. If you don't, the conversion fails and you have to update -the author file accordingly. The following command searches through the -repository and output a list of authors. - -```shell -svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq -``` - -Use the output from the last command to construct the authors file. -Create a file called `authors.txt` and add one mapping per line. - -```plaintext -janedoe = Jane Doe <janedoe@example.com> -johndoe = John Doe <johndoe@example.com> -``` - -If your SVN repository is in the standard format (trunk, branches, tags, -not nested) the conversion is simple. For a non-standard repository see -[svn2git documentation](https://github.com/nirvdrum/svn2git). The following -command will checkout the repository and do the conversion in the current -working directory. Be sure to create a new directory for each repository before -running the `svn2git` command. The conversion process takes some time. - -```shell -svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt -``` - -If your SVN repository requires a username and password add the -`--username <username>` and `--password <password>` flags to the above command. -`svn2git` also supports excluding certain file paths, branches, tags, and so on. See -[svn2git documentation](https://github.com/nirvdrum/svn2git) or run -`svn2git --help` for full documentation on all of the available options. - -Create a new GitLab project, into which you push your converted code. -Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab -repository as a Git remote and push all the changes. This pushes all commits, -branches and tags. - -```shell -git remote add origin git@gitlab.com:<group>/<project>.git -git push --all origin -git push --tags origin -``` - -## Contribute to this guide - -We welcome all contributions that would expand this guide with instructions on -how to migrate from SVN and other version control systems. + ```shell + git remote add origin git@gitlab.example.com:<group>/<project>.git + git push --all origin + git push --tags origin + ``` diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 53547e69e00..81293fb1645 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -158,7 +158,7 @@ Supported values are: | `stacked-bar` |  | NOTE: -The `dora` data source only supports the `bar` chart type. +The `dora` data source supports the `bar` and `line` chart types. ### `query` @@ -352,7 +352,7 @@ dora: title: "DORA charts" charts: - title: "DORA deployment frequency" - type: bar # only bar chart is supported at the moment + type: bar # or line query: data_source: dora params: diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index a10e261f10e..07b37b5be43 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,7 +32,7 @@ In Asana, create a Personal Access Token. Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 75f099268cb..7b39f6c7162 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -36,7 +36,7 @@ integration in GitLab. ## Configure GitLab -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index ac4b9d0769b..f058950e0f4 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,7 +14,7 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 71ca9f4f640..c3794aa1a2b 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -20,7 +20,7 @@ on the left sidebar in your project. To enable a custom issue tracker in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 3780ea37c0b..dffcc780206 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -26,7 +26,7 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index c1c48c7fb12..37d9a86f8fa 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -11,7 +11,7 @@ that is pushed to your project. To enable emails on push: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Emails on push**. 1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index b02f1a06e96..45f3653757d 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,7 +14,7 @@ This IBM product was [formerly named Rational Team Concert](https://jazz.net/blo To enable the EWM integration, in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **EWM**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index c07142d6edf..4be541d99cb 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -29,7 +29,7 @@ Complete these steps on GitHub: Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **GitHub**. 1. Ensure the **Active** checkbox is selected. @@ -39,7 +39,7 @@ Complete these steps in GitLab: 1. Optional. Select **Test settings**. 1. Select **Save changes**. -After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) +After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. ### Static or dynamic status check names diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index dc56c2669f8..afc379e7a07 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -74,7 +74,6 @@ Slack user on GitLab.com. The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) is that all the commands should be prefixed with the `/gitlab` keyword. -We are working on making this configurable in the future. For example, to show the issue number `1001` under the `gitlab-org/gitlab` project, you would do: diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index fbfa7d914a5..b2586383b43 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -10,7 +10,7 @@ Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google Hangouts). -## How it works +## Integration workflow To enable this integration, first you need to create a webhook for the room in Google Chat where you want to receive the notifications from your project. @@ -23,9 +23,9 @@ notifications to Google Chat:  -## In Google Chat +## Enable the integration in Google Chat -Select a room and create a webhook: +To enable the integration in Google Chat: 1. Enter the room where you want to receive notifications from GitLab. 1. Open the room dropdown menu on the top-left and select **Manage webhooks**. @@ -36,9 +36,22 @@ Select a room and create a webhook: For further details, see [the Google Chat documentation for configuring webhooks](https://developers.google.com/chat/how-tos/webhooks). -## In GitLab +### Enable threads in Google Chat -Enable the Google Chat integration in GitLab: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27823) in GitLab 15.4. + +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/). +1. In **Spaces**, select **+ > Create space**. +1. Enter the space name and (optionally) other details, and select **Use threaded replies**. +1. Select **Create**. + +You cannot enable threaded replies for existing Google Chat spaces. + +## Enable the integration in GitLab + +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. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index da35f0dc226..535703ff59e 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -25,7 +25,7 @@ In the Harbor instance, ensure that: GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Harbor**. 1. Turn on the **Active** toggle under **Enable Integration**. @@ -42,7 +42,9 @@ After the Harbor integration is activated: - The global variables `$HARBOR_USERNAME`, `$HARBOR_HOST`, `$HARBOR_OCI`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. - The project-level integration settings override the group-level integration settings. -## Secure your requests to the Harbor APIs +## Security considerations + +### Secure your requests to the Harbor APIs For each API request through the Harbor integration, the credentials for your connection to the Harbor API use the `username:password` combination. The following are suggestions for safe use: @@ -51,6 +53,12 @@ the `username:password` combination. The following are suggestions for safe use: - Follow the principle of least privilege (for access on Harbor) with your credentials. - Have a rotation policy on your credentials. +### CI/CD variable security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including +`$HARBOR_PASSWORD`, and send them to a third-party server. For more details, see +[CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). + ## Examples of Harbor variables in CI/CD ### Push a Docker image with kaniko diff --git a/doc/user/project/integrations/img/mattermost_add_slash_command.png b/doc/user/project/integrations/img/mattermost_add_slash_command.png Binary files differdeleted file mode 100644 index 7759efa183c..00000000000 --- a/doc/user/project/integrations/img/mattermost_add_slash_command.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_bot_auth.png b/doc/user/project/integrations/img/mattermost_bot_auth.png Binary files differdeleted file mode 100644 index a05d8da1237..00000000000 --- a/doc/user/project/integrations/img/mattermost_bot_auth.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_bot_available_commands.png b/doc/user/project/integrations/img/mattermost_bot_available_commands.png Binary files differdeleted file mode 100644 index 3232ccc3451..00000000000 --- a/doc/user/project/integrations/img/mattermost_bot_available_commands.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_gitlab_token.png b/doc/user/project/integrations/img/mattermost_gitlab_token.png Binary files differdeleted file mode 100644 index 63140503824..00000000000 --- a/doc/user/project/integrations/img/mattermost_gitlab_token.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 3ef40fdfe44..18e827f8df8 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -18,7 +18,7 @@ Prerequisites: To view the available integrations for your project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, 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). @@ -76,6 +76,7 @@ You can configure the following integrations. | [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | +| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | | [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index b2c2aea2c2b..5f7de09cc9d 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,7 +39,7 @@ network. For more details, read ## Complete these steps in GitLab -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 7dd4c1d1a8b..12575e34058 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -39,7 +39,7 @@ Display name override is not enabled by default, you need to ask your administra After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Mattermost notifications**. 1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 768acb02ee6..28a5f2eec18 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -6,48 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Mattermost slash commands **(FREE)** -If your team uses [Mattermost](https://mattermost.com/) as a chat service, you can -integrate GitLab commands into Mattermost chat. This integration enables users to -run common operations, such as creating a GitLab issue, from the Mattermost chat -environment. +You can use slash commands to run common GitLab operations, like creating an issue, +from a [Mattermost](https://mattermost.com/) chat environment. GitLab can also send events (such as `issue created`) to Mattermost as part of the -separately configured [Mattermost Notifications Service](mattermost.md). +separately configured [Mattermost notifications](mattermost.md). -## Prerequisites +## Configuration options -Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/) is required. -GitLab provides different methods of configuring Mattermost slash commands, depending -on your configuration: +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). + [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, + read the [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the - [automated configuration](#automated-configuration). -- **For all other installations**, use the [manual configuration](#manual-configuration). + [automated configuration](#configure-automatically). +- **For all other installations**, use the [manual configuration](#configure-manually). -## Automated configuration +## Configure automatically -If Mattermost is installed on the same server as GitLab, the configuration process can be -done for you by GitLab. +If Mattermost is installed on the same server as GitLab, +you can automatically configure Mattermost slash commands: -Go to the Mattermost Slash Command service on your project and select **Add to Mattermost**. +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. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Select **Add to Mattermost**, and select **Save changes**. -## Manual configuration +## Configure manually To manually configure slash commands in Mattermost, you must: -1. [Enable custom slash commands](#enable-custom-slash-commands) in Mattermost. -1. [Get configuration values](#get-configuration-values-from-gitlab) from GitLab. -1. [Create a new slash command](#create-a-slash-command) in Mattermost. -1. [Provide the Mattermost token](#provide-the-mattermost-token-to-gitlab) to GitLab. +1. [Enable custom slash commands in Mattermost](#enable-custom-slash-commands-in-mattermost). + (This step is required only for installations from source.) +1. [Get configuration values from GitLab](#get-configuration-values-from-gitlab). +1. [Create a slash command in Mattermost](#create-a-slash-command-in-mattermost). +1. [Provide the Mattermost token to GitLab](#provide-the-mattermost-token-to-gitlab). -### Enable custom slash commands - -NOTE: -Omnibus GitLab installations are preconfigured. This step is required only for -installations from source. +### Enable custom slash commands in Mattermost To enable custom slash commands from the Mattermost administrator console: @@ -58,80 +56,68 @@ To enable custom slash commands from the Mattermost administrator console: - **Enable Custom Slash Commands** - **Enable integrations to override usernames** - **Enable integrations to override profile picture icons** -1. Select **Save**, but do not close this browser tab, because you need it in +1. Select **Save**, but do not close this browser tab. You need it in a later step. ### Get configuration values from GitLab -After you enable custom slash commands in Mattermost, you need configuration -information from GitLab. To get this information: +To get configuration values from GitLab: -1. In a different browser tab than your current Mattermost session, sign in to +1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the top bar, select **Menu > Admin**. -1. In the left menu, select **Settings > Integrations**, then select - **Mattermost slash commands**. -1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** - as you need it for the next step. All other values are suggestions. -1. Do not close this browser tab, because you need it in future steps. - -Next, create a slash command in Mattermost with the values from GitLab. +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, 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. -### Create a slash command +### Create a slash command in Mattermost -To create a slash command, you need the values you obtained from GitLab in -the previous step: +To create a slash command in Mattermost: -1. In the Mattermost tab you left open when you - [enabled custom slash commands](#enable-custom-slash-commands), go to your - team page. +1. [In the Mattermost browser tab](#enable-custom-slash-commands-in-mattermost), + go to your team page. 1. Select the **{ellipsis_v}** **Settings** icon, and select **Integrations**. -1. In the left menu, select **Slash commands**. -1. Select **Add Slash Command**: - -  +1. On the left sidebar, select **Slash commands**. +1. Select **Add Slash Command**. 1. Provide a **Display Name** and **Description** for your new command. -1. Provide a **Command Trigger Word** according to your application's configuration: +1. Provide a **Command Trigger Word** based on your application's configuration: - - **If you intend to only connect one project to your Mattermost team**: Use + - **If you intend to only connect one project to your Mattermost team**, use `/gitlab` for your trigger word. - - **If you intend to connect multiple projects**: Use a trigger word that relates + - **If you intend to connect multiple projects**, use a trigger word that relates to your project, such as `/project-name` or `/gitlab-project-name`. -1. For **Request URL**, provide the value you copied from GitLab when you - [viewed configuration values](#get-configuration-values-from-gitlab). -1. For all other values, you may use the suggestions from GitLab or use your +1. For **Request URL**, [paste the value you copied from GitLab](#get-configuration-values-from-gitlab). +1. For all other values, you may use the suggestions from GitLab or your preferred values. -1. Copy the **Token** value, as you need it in a later step, and select **Done**. +1. Copy the **Token** value, and select **Done**. ### Provide the Mattermost token to GitLab -When you create a new slash command in Mattermost, it generates a token you must +Creating a slash command in Mattermost generates a token you must provide to GitLab: -1. In the GitLab browser tab from - [getting configuration values from GitLab](#get-configuration-values-from-gitlab), - select the **Active** checkbox to enable this configuration. -1. In the **Token** field, paste the token you obtained from Mattermost. - ensure that the **Active** toggle is enabled. - -  - -1. Select **Save changes** for the changes to take effect. +1. [In the GitLab browser tab](#get-configuration-values-from-gitlab), + select the **Active** checkbox. +1. In the **Token** text box, [paste the token you copied from Mattermost](#create-a-slash-command-in-mattermost). +1. Select **Save changes**. Your slash command can now communicate with your GitLab project. -## Authorizing Mattermost to interact with GitLab +## Connect your GitLab account to Mattermost -The first time a user interacts with the newly created slash commands, -Mattermost triggers an authorization process. +Prerequisite: - +- To run [slash commands](#available-slash-commands), you must have + [permission](../../permissions.md#project-members-permissions) to + perform the action in the GitLab project. -This connects your Mattermost user with your GitLab user. You can -see all authorized chat accounts in your profile's page under **Chat**. +To interact with GitLab using Mattermost slash commands: -When the authorization process is complete, you can start interacting with -GitLab using the Mattermost commands. +1. In a Mattermost chat environment, run your new slash command. +1. Select **connect your GitLab account** to authorize access. + +You can see all authorized chat accounts in your Mattermost profile page under **Chat**. ## Available slash commands @@ -139,30 +125,21 @@ The available slash commands for Mattermost are: | Command | Description | Example | | ------- | ----------- | ------- | -| <kbd>/<trigger> issue new <title> <kbd>⇧ Shift</kbd>+<kbd>↵ Enter</kbd> <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | -| <kbd>/<trigger> issue show <issue-number></kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | -| <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | - -To see a list of available commands to interact with GitLab, type the -trigger word followed by <kbd>help</kbd>. Example: `/gitlab help` - - +| `/<trigger> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | +| `/<trigger> issue show <issue-number>` | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | +| `/<trigger> deploy <environment> to <environment>` | Start the CI/CD job that deploys from one environment to another (for example, `staging` to `production`). CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | +| `/<trigger> help` | View a list of available slash commands. | `/gitlab help` | -## Permissions +## Related topics -The permissions to run the [available commands](#available-slash-commands) derive from -the [permissions you have on the project](../../permissions.md#project-members-permissions). +- [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) +- [Omnibus GitLab Mattermost](../../../integration/mattermost/index.md) ## Troubleshooting -If an event is not being triggered, confirm that the channel you're using is a public one. -Mattermost webhooks do not have access to private channels. - -If a private channel is required, you can edit the webhook's channel in Mattermost and -select a private channel. It is not possible to use different channels for -different types of notifications. All events are sent to the specified channel. - -## Further reading +When a Mattermost slash command does not trigger an event in GitLab: -- [Mattermost slash commands documentation](https://docs.mattermost.com/developer/slash-commands.html) -- [Omnibus GitLab Mattermost](../../../integration/mattermost/) +- Ensure you're using a public channel. + Mattermost webhooks do not have access to private channels. +- If you require a private channel, edit the webhook channel, + and select a private one. All events are sent to the specified channel. diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 6679bab745b..2e6954390fb 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -35,7 +35,7 @@ After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: 1. Sign in to GitLab as an administrator. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Microsoft Teams notifications**. 1. To enable the integration, select **Active**. diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 7f5414b86de..a0798da21f0 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,7 +37,7 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar Complete these steps in GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 068a2810a53..c1181169261 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -62,7 +62,7 @@ GitLab can use these to access the resource. More information about authenticati service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Prometheus**. 1. For **API URL**, provide the domain name or IP address of your server, such as @@ -83,7 +83,7 @@ You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prom with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Prometheus**. 1. Provide the domain name or IP address of your server, for example diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index cd28a7c0048..0eb3a38bb86 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -25,8 +25,8 @@ 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 **Menu > Admin**. +1. To enable the integration for your instance: + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. 1. Ensure that the **Active** toggle is enabled. @@ -36,4 +36,4 @@ notifications: 1. Optional. To test the integration, select **Test settings**. 1. Select **Save changes**. -The Pumble channel begins to receive all applicable GitLab events. +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 a989b418199..bc1d299dccf 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -10,7 +10,7 @@ Use [Redmine](https://www.redmine.org/) as the issue tracker. To enable the Redmine integration in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Redmine**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index fdcbb498621..dc6c2da0d91 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -15,7 +15,7 @@ With the GitLab spoke in ServiceNow, you can automate actions for GitLab projects, groups, users, issues, merge requests, branches, and repositories. For a full list of features, see the -[GitLab spoke documentation](https://docs.servicenow.com/bundle/orlando-servicenow-platform/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). +[GitLab spoke documentation](https://docs.servicenow.com/bundle/sandiego-application-development/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). You must [configure GitLab as an OAuth2 authentication service provider](../../../integration/oauth_provider.md), which involves creating an application and then providing the Application ID diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md new file mode 100644 index 00000000000..ea92b8b3f0b --- /dev/null +++ b/doc/user/project/integrations/shimo.md @@ -0,0 +1,34 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Shimo Workspace integration **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 with a feature flag named `shimo_integration`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. [Feature flag `shimo_integration`](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) removed. + +[Shimo](https://shimo.im/) is a productivity suite that includes documents, spreadsheets, and slideshows in one interface. With this integration, you can use the Shimo Wiki directly within GitLab instead of the [GitLab group/project wiki](../wiki/index.md). + +## Configure settings in GitLab + +To enable the Shimo Workspace integration for your group or 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 Workspace**. +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**. + +On the left sidebar, **Shimo** now appears instead of **Wiki**. + +## View the Shimo Workspace + +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 **Shimo Workspace** page, select **Go to Shimo Workspace**. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index dd0f57570aa..ae2e57a6d7f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -22,7 +22,7 @@ to control GitLab from Slack. Slash commands are configured separately. ## Configure GitLab -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 5ad344a7d8e..67d6befb5fc 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -21,7 +21,7 @@ For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. Slack slash command integrations are scoped to a project. -1. In GitLab, on the top bar, select **Menu > Projects** and find your 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. 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). diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 1e607d89e80..91beefd30ab 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,7 +15,7 @@ copy its URL. In GitLab: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index e8b2470cf13..0b487e29d26 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,7 @@ 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 **Menu > Admin**. Then, in the left sidebar, + - On the top bar, select **Main menu > Admin**. Then, in the left sidebar, select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 25fc9c4e1c3..e6071e7517d 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,7 +14,7 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **YouTrack**. 1. Select the checkbox under **Enable integration**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 787e990526d..916d566bb20 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -8,14 +8,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w The issue board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. -It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a + +You can use it as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. -It pairs issue tracking and project management, keeping everything together, -so that you don't need to jump between different platforms to organize your workflow. +Issue boards pair issue tracking and project management, keeping everything together, +so you can organize your workflow on a single platform. -Issue boards build on the existing [issue tracking functionality](issues/index.md) and -[labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned +Issue boards use [issues](issues/index.md) and [labels](labels.md). +Your issues appear as cards in vertical lists, organized by their assigned labels, [milestones](#milestone-lists), or [assignees](#assignee-lists). Issue boards help you to visualize and manage your entire process in GitLab. @@ -31,21 +32,20 @@ boards in the same project.  -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), -as shown in the following table: +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/): | Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | | -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | -| Free | Multiple | 1 | No | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | +| Free | Multiple | 1 | **{dotted-circle}** No | **{dotted-circle}** No | +| Premium | Multiple | Multiple | **{check-circle}** Yes | **{check-circle}** Yes | +| Ultimate | Multiple | Multiple | **{check-circle}** Yes | **{check-circle}** Yes | -To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. +Read more about [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards).  <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of +Watch a [video presentation](https://youtu.be/vjccjHI7aGI) (April 2020) of the issue board feature. ## Multiple issue boards @@ -68,17 +68,25 @@ GitLab automatically loads the last board you visited. ### Create an issue board +Prerequisites: + +- You must have at least the Reporter role for the project. + To create a new issue board: -1. Select the dropdown with the current board name in the upper left corner of the issue boards page. +1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. 1. Select **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. ### Delete an issue board +Prerequisites: + +- You must have at least the Reporter role for the project. + To delete the currently active issue board: -1. Select the dropdown with the current board name in the upper left corner of the issue boards page. +1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. 1. Select **Delete board**. 1. Select **Delete** to confirm. @@ -192,12 +200,11 @@ card includes: - Issue number - Assignee -## Permissions +## Ordering issues in a list -Users with at least the Reporter role can use all the functionality of the -issue board feature to create or delete lists. They can also drag issues from one list to another. +Prerequisites: -## Ordering issues in a list +- You must have at least the Reporter role for the project. When an issue is created, the system assigns a relative order value that is greater than the maximum value of that issue's project or root group. This means the issue will be at the bottom of any issue list that @@ -275,16 +282,19 @@ Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in GitLab 11.0. - As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. -You can have a board with both label lists and assignee lists. To add an -assignee list: +You can have a board with both label lists and assignee lists. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add an assignee list: 1. Select **Create list**. 1. Select **Assignee**. -1. In the dropdown, select a user. +1. In the dropdown list, select a user. 1. Select **Add to board**. Now that the assignee list is added, you can assign or unassign issues to that user @@ -295,14 +305,18 @@ To remove an assignee list, just as with a label list, select the trash icon. ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in GitLab 11.2. - You're also able to create lists of a milestone. These are lists that filter issues by the assigned -milestone, giving you more freedom and visibility on the issue board. To add a milestone list: +milestone, giving you more freedom and visibility on the issue board. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add a milestone list: 1. Select **Create list**. 1. Select **Milestone**. -1. In the dropdown, select a milestone. +1. In the dropdown list, select a milestone. 1. Select **Add to board**. Like the assignee lists, you're able to [drag issues](#move-issues-and-lists) @@ -316,14 +330,17 @@ As in other list types, select the trash icon to remove a list. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11 [with a flag](../../administration/feature_flags.md) named `iteration_board_lists`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75404) in GitLab 14.6. Feature flag `iteration_board_lists` removed. -You're also able to create lists of an iteration. -These lists filter issues by the assigned iteration. +You can create lists of issues in an iteration. + +Prerequisites: + +- You must have at least the Reporter role for the project. To add an iteration list: 1. Select **Create list**. 1. Select **Iteration**. -1. In the dropdown, select an iteration. +1. In the dropdown list, select an iteration. 1. Select **Add to board**. Like the milestone lists, you're able to [drag issues](#move-issues-and-lists) @@ -344,9 +361,13 @@ This feature is available both at the project and group level. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a video overview, see [Epics Swimlanes Walkthrough - 13.6](https://www.youtube.com/watch?v=nHC7-kz5P2g) (November 2020). +Prerequisites: + +- You must have at least the Reporter role for the project. + To group issues by epic in an issue board: -1. Select the **Group by** dropdown button. +1. Select **Group by**. 1. Select **Epic**.  @@ -375,8 +396,7 @@ You can also [drag issues](#move-issues-and-lists) to change their position and ## Work In Progress limits **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. @@ -389,6 +409,10 @@ Examples: - You have a list with five issues with a limit of five. When you move another issue to that list, the list's header displays **6/5**, with the six shown in red. +Prerequisites: + +- You must have at least the Reporter role for the project. + To set a WIP limit for a list: 1. Navigate to a Project or Group board of which you're a member. @@ -399,8 +423,7 @@ To set a WIP limit for a list: ## Blocked issues **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. -> - [View blocking issues when hovering over blocked icon](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10: View blocking issues when hovering over the "blocked" icon. If an issue is [blocked by another issue](issues/related_issues.md#blocking-issues), an icon appears next to its title to indicate its blocked status. @@ -423,9 +446,6 @@ When you hover over the blocked icon (**{issue-block}**), a detailed information - Change issue labels (by dragging an issue between lists). - Close an issue (by dragging it to the **Closed** list). -If you're not able to do some of the things above, make sure you have the right -[permissions](#permissions). - ### Edit an issue > Editing title, iteration, and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1. @@ -433,6 +453,10 @@ If you're not able to do some of the things above, make sure you have the right You can edit an issue without leaving the board view. To open the right sidebar, select an issue card (not its title). +Prerequisites: + +- You must have at least the Reporter role for the project. + You can edit the following issue attributes in the right sidebar: - Assignees @@ -462,6 +486,10 @@ at the end of the lists, before **Closed**. To move and reorder lists, drag them Removing a list doesn't have any effect on issues and labels, as it's just the list view that's removed. You can always create it again later if you need. +Prerequisites: + +- You must have at least the Reporter role for the project. + To remove a list from an issue board: 1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). @@ -473,6 +501,10 @@ To remove a list from an issue board: > The **Add issues** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57329) in GitLab 13.11. +Prerequisites: + +- You must have at least the Reporter role for the project. + If your board is scoped to one or more attributes, go to the issues you want to add and apply the same attributes as your board scope. @@ -488,6 +520,11 @@ The issue should now show in the `Doing` list on your issue board. > The **Remove from board** button was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229507) in GitLab 13.10. When an issue should no longer belong to a list, you can remove it. + +Prerequisites: + +- You must have at least the Reporter role for the project. + The steps depend on the scope of the list: 1. To open the right sidebar, select the issue card. @@ -502,6 +539,10 @@ The steps depend on the scope of the list: You can use the filters on top of your issue board to show only the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). +Prerequisites: + +- You must have at least the Reporter role for the project. + You can filter by the following: - Assignee @@ -577,6 +618,40 @@ into a different list. Learn about possible effects in [Dragging issues between To move a list, select its top bar, and drag it horizontally. You can't move the **Open** and **Closed** lists, but you can hide them when editing an issue board. +#### Move an issue to the start of the list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4. + +You can move issues to the top of the list with a menu shortcut. + +Your issue is moved to the top of the list even if other issues are hidden by a filter. + +Prerequisites: + +- You must at least have the Reporter role for the project. + +To move an issue to the start of the list: + +1. In an issue board, hover over the card of the issue you want to move. +1. Select the vertical ellipsis (**{ellipsis_v}**), then **Move to start of list**. + +#### Move an issue to the end of the list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367473) in GitLab 15.4. + +You can move issues to the bottom of the list with a menu shortcut. + +Your issue is moved to the bottom of the list even if other issues are hidden by a filter. + +Prerequisites: + +- You must at least have the Reporter role for the project. + +To move an issue to the end of the list: + +1. In an issue board, hover over the card of the issue you want to move. +1. Select the vertical ellipsis (**{ellipsis_v}**), then **Move to end of list**. + #### Dragging issues between lists To move an issue to another list, select the issue card and drag it onto that list. @@ -593,8 +668,7 @@ and the target list. ### Multi-select issue cards -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. -> - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md) named `board_multi_select` in GitLab 14.0. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an @@ -605,6 +679,10 @@ The feature is not ready for production use. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. +Prerequisites: + +- You must have at least the Reporter role for the project. + To select and move multiple cards: 1. Select each card with <kbd>Control</kbd>+`Click` on Windows or Linux, or <kbd>Command</kbd>+`Click` on MacOS. @@ -612,22 +690,6 @@ To select and move multiple cards:  -### First time using an issue board - -> - The automatic creation of the **To Do** and **Doing** lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. In GitLab 13.7 and later, the **To Do** and **Doing** columns are not automatically created. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. -The **To Do** and **Doing** columns are no longer automatically created. - -In GitLab 13.5 and 13.6, the first time you open an issue board, you are presented with the default lists -(**Open**, **To Do**, **Doing**, and **Closed**). - -If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and -their lists appear as empty. If any of them already exists, the list is filled with the issues that -have that label. - ## Tips A few things to remember: diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index 41de91d9bd7..ef864dc2743 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4. -In order to communicate synchronously for incidents management, -GitLab allows to associate a Zoom meeting with an issue. +To communicate synchronously for incidents management, +you can associate a Zoom meeting with an issue. After you start a Zoom call for a fire-fight, you need a way to associate the conference call with an issue. This is so that your team members can join swiftly without requesting a link. @@ -36,6 +36,9 @@ You are only allowed to attach a single Zoom meeting to an issue. If you attempt to add a second Zoom meeting using the `/zoom` quick action, it doesn't work. You need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. +Users on GitLab Premium and higher can also +[add multiple Zoom links to incidents](../../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident). + ## Removing an existing Zoom meeting from an issue Similarly to adding a Zoom meeting, you can remove it with a quick action: diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 402ce4bebec..5a1e66c8f7d 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -22,7 +22,7 @@ confidential checkbox and hit **Save changes**. 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. - + ## Modify issue confidentiality @@ -39,9 +39,12 @@ The second way is to locate the **Confidentiality** section in the sidebar and s |  |  | Every change from regular to confidential and vice versa, is indicated by a -system note in the issue's comments. +system note in the issue's comments: - + + +- **{eye-slash}** The issue is made confidential. +- **{eye}** The issue is made public. When an issue is made confidential, only users with at least the Reporter role for the project have access to the issue. @@ -51,7 +54,7 @@ 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 eye-slash (**{eye-slash}**) icon +regular one. In the issues index page view, you can see the confidential (**{eye-slash}**) icon next to the issues that are marked as confidential:  @@ -61,7 +64,7 @@ you cannot see confidential issues at all. --- -Likewise, while inside the issue, you can see the eye-slash icon right next to +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. diff --git a/doc/user/project/issues/img/confidential_issues_create.png b/doc/user/project/issues/img/confidential_issues_create.png Binary files differdeleted file mode 100644 index 0a141eb39f8..00000000000 --- a/doc/user/project/issues/img/confidential_issues_create.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..ff489ad8605 --- /dev/null +++ b/doc/user/project/issues/img/confidential_issues_create_v15_4.png diff --git a/doc/user/project/issues/img/confidential_issues_system_notes.png b/doc/user/project/issues/img/confidential_issues_system_notes.png Binary files differdeleted file mode 100644 index 355be80ecb6..00000000000 --- a/doc/user/project/issues/img/confidential_issues_system_notes.png +++ /dev/null diff --git a/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png b/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png Binary files differnew file mode 100644 index 00000000000..e448f609112 --- /dev/null +++ b/doc/user/project/issues/img/confidential_issues_system_notes_v15_4.png diff --git a/doc/user/project/issues/img/issue_weight_v13_11.png b/doc/user/project/issues/img/issue_weight_v13_11.png Binary files differdeleted file mode 100644 index 842c154ea49..00000000000 --- a/doc/user/project/issues/img/issue_weight_v13_11.png +++ /dev/null diff --git a/doc/user/project/issues/img/related_issue_block_v15_3.png b/doc/user/project/issues/img/related_issue_block_v15_3.png Binary files differindex 827ddeabf10..942f7a33fe0 100644 --- a/doc/user/project/issues/img/related_issue_block_v15_3.png +++ b/doc/user/project/issues/img/related_issue_block_v15_3.png diff --git a/doc/user/project/issues/img/related_issues_add_v15_3.png b/doc/user/project/issues/img/related_issues_add_v15_3.png Binary files differindex 7c6edf61427..28739c0b909 100644 --- a/doc/user/project/issues/img/related_issues_add_v15_3.png +++ b/doc/user/project/issues/img/related_issues_add_v15_3.png diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index fcc53a239dc..21d7fb0a764 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -13,15 +13,56 @@ When you have a lot of issues, it can be hard to get an overview. With weighted issues, you can get a better idea of how much time, value, or complexity a given issue has or costs. -You can set the weight of an issue during its creation, by changing the -value in the dropdown menu. You can set it to a non-negative integer -value from 0, 1, 2, and so on. -You can remove weight from an issue as well. -A user with a Reporter role (or above) can set the weight. +## View the issue weight -This value appears on the right sidebar of an individual issue, as well as -in the issues page next to a weight icon (**{weight}**). +You can view the issue weight on: -As an added bonus, you can see the total sum of all issues on the milestone page. +- The right sidebar of each issue. +- The issues page, next to a weight icon (**{weight}**). +- [Issue boards](../issue_board.md), next to a weight icon (**{weight}**). +- The [milestone](../milestones/index.md) page, as a total sum of issue weights. - +## Set the issue weight + +Prerequisites: + +- You must have at least the Reporter role for the project. + +You can set the issue weight when you create or edit an issue. + +You must enter whole, positive numbers. + +When you change the weight of an issue, the new value overwrites the previous value. + +### When you create an issue + +To set the issue weight when you [create an issue](managing_issues.md#create-an-issue), enter a +number under **Weight**. + +### From an existing issue + +To set the issue weight from an existing issue: + +1. Go to the issue. +1. On the right sidebar, in the **Weight** section, select **Edit**. +1. Enter the new weight. +1. Select any area outside the dropdown list. + +### From an issue board + +To set the issue weight when you [edit an issue from an issue board](../issue_board.md#edit-an-issue): + +1. Go to your issue board. +1. Select an issue card (not its title). +1. On the right sidebar, in the **Weight** section, select **Edit**. +1. Enter the new weight. +1. Select any area outside the dropdown list. + +## Remove issue weight + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To remove the issue weight, follow the same steps as when you [set the issue weight](#set-the-issue-weight), +and select **remove weight**. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 40e5a6d6a92..b4edb238479 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -33,7 +33,7 @@ Prerequisites: To create an issue: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Either: - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. @@ -56,7 +56,7 @@ Prerequisites: To create an issue from a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. 1. In the top 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 @@ -103,7 +103,7 @@ Prerequisites: To create an issue from a project issue board: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Issues > Boards**. 1. At the top of a board list, select **New issue** (**{plus-square}**). 1. Enter the issue's title. @@ -111,7 +111,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 **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. Select **Issues > Boards**. 1. At the top of a board list, select **New issue** (**{plus-square}**). 1. Enter the issue's title. @@ -138,7 +138,7 @@ Prerequisites: To email an issue to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **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}**). @@ -271,7 +271,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues**. 1. Select **Edit issues**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -304,7 +304,7 @@ Prerequisites: To edit multiple issues at the same time: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. 1. Select **Edit issues**. A sidebar on the right of your screen appears. 1. Select the checkboxes next to each issue you want to edit. @@ -458,7 +458,8 @@ The default issue closing pattern regex: #### Disable automatic issue closing -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/240922) in GitLab 15.4: The referenced issue's project setting is checked instead of the project of the commit or merge request. You can disable the automatic issue closing feature on a per-project basis in the [project's settings](../settings/index.md). @@ -469,23 +470,18 @@ Prerequisites: To disable automatic issue closing: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. -1. Select **Auto-close referenced issues on default branch**. +1. Clear the **Auto-close referenced issues on default branch** checkbox. 1. Select **Save changes**. Referenced issues are still displayed, but are not closed automatically. -The automatic issue closing is disabled by default in a project if the project has the issue tracker -disabled. If you want to enable automatic issue closing, make sure to -[enable GitLab Issues](../settings/index.md#configure-project-visibility-features-and-permissions). - Changing this setting applies only to new merge requests or commits. Already closed issues remain as they are. -If issue tracking is enabled, disabling automatic issue closing only applies to merge requests -attempting to automatically close issues in the same project. -Merge requests in other projects can still close another project's issues. +Disabling automatic issue closing only applies to issues in the project where the setting was disabled. +Merge requests and commits in this project can still close another project's issues. #### Customize the issue closing pattern **(FREE SELF)** @@ -602,7 +598,7 @@ GitLab displays the results on-screen, but you can also > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues > List**. 1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. @@ -644,10 +640,15 @@ To copy the issue's email address: > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.5. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.9. Feature flags `real_time_issue_sidebar` and `broadcast_issue_updates` removed. -Assignees in the sidebar are updated in real time. -When you're viewing an issue and somebody changes its assignee, +Some sections of the right sidebar are updated in real time. +When you're viewing an issue and somebody changes one of the values, you can see the change without having to refresh the page. +The following sections are updated in real time: + +- [Assignee](#assignee) +- Labels, [if enabled](../labels.md#real-time-changes-to-labels) + ## Assignee An issue can be assigned to one or [more users](multiple_assignees_for_issues.md). @@ -685,6 +686,7 @@ Up to five similar issues, sorted by most recently updated, are displayed below > - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in GitLab 13.4 and later. > - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218618) in GitLab 15.4: health status is visible on issue cards in issue boards. To help you track issue statuses, you can assign a status to each issue. This status marks issues as progressing as planned or needing attention to keep on schedule. @@ -703,7 +705,11 @@ To edit health status of an issue: - Needs attention (amber) - At risk (red) -You can then see the issue's status in the issues list and the epic tree. +You can see the issue’s health status in: + +- Issues list +- Epic tree +- Issue cards in issue boards After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 9dc361b403f..d1e62a76103 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -29,7 +29,7 @@ Prerequisites: To link one issue to another: -1. In the **Linked issues** section of an issue, +1. In the **Linked items** section of an issue, select the add linked issue button (**{plus}**). 1. Select the relationship between the two issues. Either: - **relates to** @@ -61,7 +61,7 @@ You can also add a linked issue from a commit message or the description in anot ## Remove a linked issue -In the **Linked issues** section of an issue, select the remove button (**{close}**) on the +In the **Linked items** section of an issue, select the remove button (**{close}**) on the right-side of each issue token to remove. Due to the bi-directional relationship, the relationship no longer appears in either issue. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 62c5489d9c3..13c93fadf6e 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -58,7 +58,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. Or: @@ -75,7 +75,7 @@ project or group path where it was created. To view the **group's labels**: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. Or: @@ -97,7 +97,7 @@ Prerequisites: To create a project label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -131,7 +131,7 @@ To do so: To create a group label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. 1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You @@ -171,7 +171,7 @@ Prerequisites: To edit a **project** label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -179,7 +179,7 @@ To edit a **project** label: To edit a **group** label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. 1. Next to the label you want to edit, select **Edit** (**{pencil}**). @@ -197,7 +197,7 @@ Prerequisites: To delete a **project** label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Either: @@ -210,7 +210,7 @@ To delete a **project** label: To delete a **group** label: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Labels**. 1. Either: @@ -240,7 +240,7 @@ Prerequisites: To promote a project label to a group label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. @@ -291,7 +291,7 @@ Prerequisites: To add the default labels to the project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Select **Generate a default set of labels**. @@ -430,7 +430,7 @@ Prerequisites: To prioritize a label: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Labels**. 1. Next to a label you want to prioritize, select the star (**{star-o}**). diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 4a6272a0ca3..8d8169e8454 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -68,7 +68,7 @@ Prerequisite: To add a user to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. 1. Enter an email address and select a [role](../../permissions.md). @@ -106,7 +106,7 @@ Prerequisite: To add groups to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite a group**. 1. Select a group. @@ -131,7 +131,7 @@ Prerequisite: To import users: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. @@ -175,7 +175,7 @@ Prerequisites: To remove a member from a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Next to the project member you want to remove, select **Remove member**. 1. Optional. In the confirmation box, select the @@ -197,7 +197,7 @@ You can filter and sort members in a project. ### Display inherited members -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. @@ -206,7 +206,7 @@ You can filter and sort members in a project. ### Display direct members -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press <kbd>Enter</kbd>. @@ -229,7 +229,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last GitLab users can request to become a member of a project. -1. On the top bar, select **Menu > Projects** and find the project you want to be a member of. +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**.  @@ -253,7 +253,7 @@ Prerequisite: - You must be the project owner. -1. On the top bar, select **Menu > Projects** and find 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 **Visibility, project features, permissions**. 1. Under **Project visibility**, select **Users can request access**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 3d5b855a9d3..ee161deaabb 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -48,6 +48,7 @@ After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. - The project is listed on the group dashboard. +- All members, including members from the ancestors of the 'Engineering' group, gain access to 'Project Acme' with an access level based on the outcome of [maximum access level](#maximum-access-level). When you share a project, be aware of the following restrictions and outcomes: @@ -83,7 +84,7 @@ The following outcomes occur: ## Share project with group lock -It is possible to prevent projects in a group from +It is possible to prevent projects in a group from [sharing a project with another group](../members/share_project_with_groups.md). This allows for tighter control over project access. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index c9278c19322..32548215054 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -32,8 +32,9 @@ use the default approval rules from the target (upstream) project, not the sourc To add a merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**, and then select **Add approval rule**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Select **Add approval rule**. 1. Add a human-readable **Rule name**. 1. Set the number of required approvals in **Approvals required**. A value of `0` makes [the rule optional](#configure-optional-approval-rules), and any number greater than `0` @@ -65,8 +66,9 @@ to existing merge requests: To edit a merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**, and then select **Edit**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Select **Edit** next to the rule you want to edit. 1. Optional. Change the **Rule name**. 1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. 1. Add or remove eligible approvers, as needed: @@ -155,11 +157,11 @@ approve in these ways: If you add [code owners](../../code_owners.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Locate **All eligible users** and select the number of approvals required: +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. +1. Locate the **All eligible users** rule, and select the number of approvals required: - +  You can also [require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) @@ -182,9 +184,10 @@ granting them push access: 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-of-users), based on the Reporter role. -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select **Add approval rule** or **Update approval rule** and target the protected branch. +1. Go to your project and select **Settings > Merge requests**. +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.  @@ -226,12 +229,12 @@ Approval rules are often relevant only to specific branches, like your approval rule for certain branches: 1. [Create an approval rule](#add-an-approval-rule). -1. Go to your project and select **Settings**. -1. Expand **Merge request (MR) approvals**. +1. Go to your project and select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval rules**. 1. Select a **Target branch**: - To apply the rule to all branches, select **All branches**. - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). - - To apply the rule to a specific branch, select it from the list: + - To apply the rule to a specific branch, select it from the list. 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 3ca8ddb508a..4fdf6d46b8b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -16,8 +16,8 @@ those rules are applied as a merge request moves toward completion. To view or edit merge request approval settings: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. +1. Go to your project and select **Settings > Merge requests**. +1. Expand **Approvals**. ### Approval settings @@ -44,9 +44,9 @@ You can further define what happens to existing approvals when commits are added By default, the author of a merge request cannot approve it. To change this setting: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Clear the **Prevent approval by author** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + clear the **Prevent approval by author** checkbox. 1. Select **Save changes**. Authors can edit the approval rule in an individual merge request and override @@ -68,9 +68,9 @@ the project level or [instance level](../../../admin_area/merge_requests_approva you can prevent committers from approving merge requests that are partially their own. To do this: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent approvals by users who add commits** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Prevent approvals by users who add commits**. If this checkbox is cleared, an administrator has disabled it [at the instance level](../../../admin_area/merge_requests_approvals.md), and it can't be changed at the project level. @@ -94,9 +94,9 @@ By default, users can override the approval rules you [create for a project](rul on a per-merge-request basis. If you don't want users to change approval rules on merge requests, you can disable this setting: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent editing approval rules in merge requests** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Prevent editing approval rules in merge requests**. 1. Select **Save changes**. This change affects all open merge requests. @@ -112,9 +112,9 @@ permission enables an electronic signature for approvals, such as the one define 1. Enable password authentication for the web interface, as described in the [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Require user password to approve** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Require user password to approve**. 1. Select **Save changes**. ## Remove all approvals when commits are added to the source branch @@ -123,9 +123,9 @@ By default, an approval on a merge request remains in place, even if you add mor after the approval. If you want to remove all existing approvals on a merge request when more changes are added to it: -1. Go to your project and select **Settings > General**. -1. Expand **Merge request (MR) approvals**. -1. Select the **Remove all approvals when commits are added to the source branch** checkbox. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Remove all approvals when commits are added to the source branch**. 1. Select **Save changes**. Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) @@ -143,10 +143,9 @@ Prerequisite: To do this: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge request approvals**. -1. Select **Remove approvals by Code Owners if their files changed**. +1. On the left sidebar, select **Settings > Merge requests**. +1. In the **Merge request approvals** section, scroll to **Approval settings** and + select **Remove approvals by Code Owners if their files changed**. 1. Select **Save changes**. ## Code coverage check approvals diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 14f3979cf34..2040995280e 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -7,61 +7,106 @@ type: reference, concepts # Cherry-pick changes **(FREE)** -GitLab implements Git's powerful feature to -[cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") -with a **Cherry-pick** button in merge requests and commit details. +In Git, *cherry-picking* is taking a single commit from one branch and adding it +as the latest commit on another branch. The rest of the commits in the source branch +are not added to the target. You should cherry-pick a commit when you need the +change contained in a single commit, but you can't or don't want to pull the +entire contents of that branch into another. -## Cherry-pick a merge request +You can use the GitLab UI to cherry-pick single commits or entire merge requests. +You can even cherry-pick a commit from [a fork of your project](#cherry-pick-into-a-project). -After the merge request has been merged, a **Cherry-pick** button displays -to cherry-pick the changes introduced by that merge request. +NOTE: +Support for tracking commits cherry-picked from the command line +is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). - +## Cherry-pick example + +In this example of cherry-picking, a Git repository has two branches: `develop` and `main`. +This example shows a cherry-picked commit from one branch being added to another: + +```mermaid +gitGraph + commit id: "A" + branch develop + commit id:"B" + checkout main + commit id:"C" + checkout develop + commit id:"D" + checkout main + commit id:"E" + cherry-pick id:"B" + commit id:"G" + checkout develop + commit id:"H" +``` -After you select that button, a modal displays a -[branch filter search box](../repository/branches/index.md#branch-filter-search-box) -where you can choose to either: +In this example, a cherry-pick of commit `B` from the `develop` branch is added +after commit `E` in the `main` branch. -- Cherry-pick the changes directly into the selected branch. -- Create a new merge request with the cherry-picked changes. +Commit `G` is added after the cherry-pick. -### Track a cherry-pick +## Cherry-pick all changes from a merge request -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. +After a merge request is merged, you can cherry-pick all changes introduced +by the merge request: -When you cherry-pick a merge commit, GitLab displays a system note to the related merge -request thread. It crosslinks the new commit and the existing 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. Scroll to the merge request reports section, and find the **Merged by** report. +1. In the top right, select **Cherry-pick**: - +  +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. +## Cherry-pick a single commit -NOTE: -We only track cherry-pick executed from GitLab (both UI and API). Support for tracking cherry-picked commits through the command line -is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). +You can cherry-pick a single commit from multiple locations in your GitLab project. -## Cherry-pick a commit +### From a project's commit list -You can cherry-pick a commit from the commit details page: +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. Select the title of the commit you want to cherry-pick. +1. In the modal window, select the project and branch to cherry-pick into. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -Similar to cherry-picking a merge request, you can cherry-pick the changes -directly into the target branch or create a new merge request to cherry-pick the -changes. +### From a merge request -When cherry-picking merge commits, the mainline is always the -first parent. If you want to use a different mainline, you need to do that -from the command line. +You can cherry-pick commits from any merge request in your project, regardless of +whether the merge request is open or closed. To cherry-pick a commit from the +list of commits included in a merge request: -Here's a quick example to cherry-pick a merge commit using the second parent as the -mainline: +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. In the merge request's secondary menu, select **Commits** to display the commit details page. +1. Select the title of the commit you want to cherry-pick. +1. In the top 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. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. -```shell -git cherry-pick -m 2 7a39eb0 -``` +### From the file view of a repository -### Cherry-pick into a project +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 + changed by the commit. +1. Select **History**, then select the title of the commit you want to cherry-pick. +1. In the top 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. +1. Optional. Select **Start a new merge request with these changes**. +1. Select **Cherry-pick**. + +## Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11 behind a [feature flag](../../feature_flags.md), disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0. @@ -70,25 +115,38 @@ You can cherry-pick merge requests from the same project, or forks of the same project, from the GitLab user interface: 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. Select the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. +1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  1. Optional. Select **Start a new merge request** if you're ready to create a merge request. 1. Select **Cherry-pick**. +## View system notes for cherry-picked commits + +When you cherry-pick a merge commit in the GitLab UI or API, GitLab adds a system note +to the related merge request thread in the format **{cherry-pick-commit}** +`[USER]` **picked the changes into the branch** `[BRANCHNAME]` with commit** `[SHA]` `[DATE]`: + + + +The system note crosslinks the new commit and the existing merge request. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. + ## Related topics -- The [Commits API](../../../api/commits.md) enables you to add custom messages - to changes you cherry-pick through the API. +- Use the [Commits API](../../../api/commits.md) to add custom messages + to changes when you use the API to cherry-pick. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Selecting a different parent commit when cherry-picking -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +When you cherry-pick a merge commit in the GitLab UI, the mainline is always the +first parent. Use the command line to cherry-pick with a different mainline. + +Here's a quick example to cherry-pick a merge commit using the second parent as the +mainline: + +```shell +git cherry-pick -m 2 7a39eb0 +``` diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 6f9bc452b96..99a1739b1a4 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 **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General** and expand **Merge requests**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, 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). diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index f30b20e9d34..1a44126f7ff 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -14,7 +14,7 @@ There are many different ways to create a merge request. You can create a merge request from the list of merge requests. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. 1. In the top right, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. @@ -43,7 +43,7 @@ You can create a merge request when you add, edit, or upload a file to a reposit You can create a merge request when you create a branch. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Repository > Branches**. 1. Type a branch name and select **New branch**. 1. Above the file list, on the right side, select **Create merge request**. @@ -90,7 +90,7 @@ to reduce the need for editing merge requests manually through the UI. You can create a merge request from your fork to contribute back to the main project. -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Main menu > Projects** and 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. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch. @@ -120,7 +120,7 @@ Prerequisites: To create a merge request by sending an email: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. 1. In the top right, select **Email a new merge request to this project**. An email address is displayed. Copy this address. @@ -165,7 +165,7 @@ scenarios when you create a new merge request: To have merge requests from a fork by default target your own fork (instead of the upstream project), you can change the default. -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Settings > General > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 893b2bc6811..f997898f5a5 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -12,7 +12,7 @@ Export all the data collected from a project's merge requests into a comma-separ To export merge requests to a CSV file: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** . 1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures the file can be emailed to a variety of email providers. diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md new file mode 100644 index 00000000000..5b88e69357c --- /dev/null +++ b/doc/user/project/merge_requests/dependencies.md @@ -0,0 +1,163 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, concepts +--- + +# Merge request dependencies **(PREMIUM)** + +A single feature can span several merge requests, spread out across multiple projects, +and the order in which the work merges can be significant. Use merge request dependencies +when it's important to merge work in a specific order. Some examples: + +- Ensure changes to a required library are merged before changes to a project that + imports the library. +- Prevent a documentation-only merge request from merging before the feature work + is itself merged. +- Require a merge request updating a permissions matrix to merge, before merging work + from someone who hasn't yet been granted permissions. + +If your project `me/myexample` imports a library from `myfriend/library`, +you might want to update your project to use a new feature in `myfriend/library`. +However, if you merge changes to your project before the external library adds the +new feature, you would break the default branch in your project. A merge request +dependency prevents your work from merging too soon: + +```mermaid +graph TB + A['me/myexample' project] + B['myfriend/library' project] + C[Merge request #1:<br>Create new version 2.5] + D[Merge request #2:<br>Add version 2.5<br>to build] + A-->|contains| D + B---->|contains| C + D-.->|depends on| C + C-.->|blocks| D +``` + +You could mark your `me/myexample` merge request as a [draft](drafts.md) +and explain why in the comments. However, this approach is manual and does not scale, especially +if your merge request relies on several others in multiple projects. Instead, +use the draft (or ready) state to track the readiness of an individual +merge request, and a merge request dependency to enforce merge order. + +NOTE: +Merge request dependencies are a **PREMIUM** feature, but this restriction is +enforced only for the dependent merge request. A merge request in a **PREMIUM** +project can depend on a merge request in a **FREE** project, but a merge request +in a **FREE** project cannot be marked as dependent. + +## View dependencies for a merge request + +If a merge request is dependent on another, the merge request reports section shows +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. 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**. +1. Select **Expand** to view the title, milestone, assignee, and pipeline status + of each dependency. + +Until your merge request's dependencies all merge, your merge request +cannot be merged. The message +**Merge blocked: you can only merge after the above items are resolved** displays. + +### Closed merge requests + +Closed merge requests still prevent their dependents from being merged, because +a merge request can close regardless of whether or not the planned work actually merged. + +If a merge request closes and the dependency is no longer relevant, +remove it as a dependency to unblock the dependent merge request. + +## Create a new dependent merge request + +When you create a new merge request, you can prevent it from merging until after +other specific work merges, even if the merge request is in a different project. + +Prerequisites: + +- You must have at least the Developer role or be allowed to create merge requests in the project. +- The dependent merge request must be in a project in a **PREMIUM** or higher tier. + +To create a new merge request and mark it as dependent on another: + +1. [Create a new merge request](creating_merge_requests.md). +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 + are in the form of `path/to/project!merge_request_id`. +1. Select **Create merge request**. + +## Edit a merge request to add a dependency + +You can edit an existing merge request and mark it as dependent on another. + +Prerequisite: + +- You must have at least the Developer role or be allowed to edit merge requests in the project. + +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. 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 + are in the form of `path/to/project!merge_request_id`. + +## Remove a dependency from a merge request + +You can edit a dependent merge request and remove a dependency. + +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. Select **Edit**. +1. Scroll to **Merge request dependencies** and select **Remove** next to the reference + for each dependency you want to remove. + + NOTE: + Dependencies for merge requests you don't have access to are displayed as + **1 inaccessible merge request**, and can be removed the same way. +1. Select **Save changes**. + +## Troubleshooting + +### API support for managing merge request dependencies + +No API support exists for managing dependencies. For more information, read +[issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551). + +### Preserving dependencies on project import or export + +Dependencies are not preserved when projects are imported or exported. For more +information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549). + +### Complex merge order dependencies are unsupported + +GitLab supports direct dependencies between merge requests, but does not support +[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). + +Acceptable dependency patterns include: + +- A single merge request can directly depend on a single merge request. +- A single merge request can directly depend on multiple merge requests. +- Multiple merge requests can directly depend on a single merge request. + +The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported: + +```mermaid +graph LR; + A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] + B-->|depends on| C[mycorp/example!100] +``` diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 4bb6034c0bd..695c6d7e612 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -20,6 +20,7 @@ the **Merge** button until you remove the **Draft** flag: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. +> `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4. There are several ways to flag a merge request as a draft: @@ -29,8 +30,7 @@ There are several ways to flag a merge request as a draft: below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) - in a comment. This quick action is a toggle, and can be repeated to change the status - back to Ready. + in a comment. GitLab 15.4 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) the toggle behavior of `/draft`. To mark a merge request as ready, use `/ready`. - **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and adding this text again in a later commit doesn't mark the diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 09ee828ffd3..9475c0d60ab 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -66,7 +66,7 @@ After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. +- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged. - Preview continuous integration [pipelines on the merge request widget](widgets.md). - Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). diff --git a/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png b/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png Binary files differnew file mode 100644 index 00000000000..7ed780d4389 --- /dev/null +++ b/doc/user/project/merge_requests/img/cancel-mwps_v15_4.png diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png Binary files differdeleted file mode 100644 index c98821548f8..00000000000 --- a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png Binary files differdeleted file mode 100644 index 8b51503419b..00000000000 --- a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png Binary files differdeleted file mode 100644 index 919b576fcc6..00000000000 --- a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v12_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png Binary files differnew file mode 100644 index 00000000000..d18c4aaec20 --- /dev/null +++ b/doc/user/project/merge_requests/img/cherry_pick_mr_timeline_v15_4.png diff --git a/doc/user/project/merge_requests/img/cherry_pick_v15_4.png b/doc/user/project/merge_requests/img/cherry_pick_v15_4.png Binary files differnew file mode 100644 index 00000000000..174bb113961 --- /dev/null +++ b/doc/user/project/merge_requests/img/cherry_pick_v15_4.png diff --git a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png b/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png Binary files differdeleted file mode 100644 index 4edf0648794..00000000000 --- a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/dependencies_view_v15_3.png b/doc/user/project/merge_requests/img/dependencies_view_v15_3.png Binary files differnew file mode 100644 index 00000000000..d044e28046f --- /dev/null +++ b/doc/user/project/merge_requests/img/dependencies_view_v15_3.png diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png Binary files differdeleted file mode 100644 index 9487264b41a..00000000000 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_enable.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.png Binary files differdeleted file mode 100644 index 70fa2efc855..00000000000 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_status.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 differnew file mode 100644 index 00000000000..f042912d470 --- /dev/null +++ b/doc/user/project/merge_requests/img/mwps_v15_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 35ec075c674..500fb95c193 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,7 +27,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. @@ -36,7 +36,7 @@ Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd> To view merge requests for all projects in a group: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. @@ -160,13 +160,11 @@ change and whether you need access to a development environment: ## Assign a user to a merge request -When a merge request is created, it's assigned by default to the person who created it. -This person owns the merge request, but isn't responsible for [reviewing it](reviews/index.md). -To assign the merge request to someone else, use the `/assign @user` +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 **Menu > Projects** and find your project. +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 right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit**. @@ -186,7 +184,7 @@ accountable for it: To assign multiple assignees to a merge request, use the `/assign @user` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a text area, or: -1. On the top bar, select **Menu > Projects** and find your project. +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 right sidebar, expand the right sidebar and locate the **Assignees** section. 1. Select **Edit** and, from the dropdown list, select all users you want diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 6bfef6ab134..6242a77e931 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,141 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: 'dependencies.md' +remove_date: '2022-11-22' --- -# Merge request dependencies **(PREMIUM)** +This document was moved to [another location](dependencies.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in GitLab 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in GitLab 12.4. -> - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in GitLab 12.4. - -Merge request dependencies allows a required order of merging -between merge requests to be expressed. If a merge request "depends on" another, -then it cannot be merged until its dependency is itself merged. - -NOTE: -Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **FREE** -project can be a dependency of a **PREMIUM** merge request, but not -the other way around. - -## Use cases - -- Ensure changes to a library are merged before changes to a project that - imports the library. -- Prevent a documentation-only merge request from being merged before the merge request - implementing the feature to be documented. -- Require a merge request updating a permissions matrix to be merged before merging a - merge request from someone who hasn't yet been granted permissions. - -It is common for a single logical change to span several merge requests, spread -out across multiple projects, and the order in which they are merged can be -significant. - -For example, given a project `mycorp/awesome-project` that imports a library -at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** -require changes to `awesome-lib`, and so necessitate two merge requests. Merging -the `awesome-project` merge request before the `awesome-lib` one would -break the default branch. - -The `awesome-project` merge request could be [marked as **Draft**](drafts.md), -and the reason for the draft stated included in the comments. However, this -requires the state of the `awesome-lib` merge request to be manually -tracked, and doesn't scale well if the `awesome-project` merge request -depends on changes to **several** other projects. - -By making the `awesome-project` merge request depend on the -`awesome-lib` merge request instead, this relationship is -automatically tracked by GitLab, and the draft state can be used to -communicate the readiness of the code in each individual merge request -instead. - -## Configuration - -To continue the above example, you can configure a dependency when creating the -new merge request in `awesome-project` (or by editing it, if it already exists). -The dependency needs to be configured on the **dependent** merge -request. There is a **Merge request dependencies** section in the form: - - - -Anyone who can edit a merge request can change the list of dependencies. - -New dependencies can be added by reference, or by URL. To remove a dependency, -press the **X** by its reference. - -As dependencies can be specified across projects, it's possible that someone else -has added a dependency for a merge request in a project you don't have access to. -These are shown as a simple count: - - - -If necessary, you can remove all the dependencies like this by pressing the -**X**, just as you would for a single, visible dependency. - -Once you're finished, press the **Save changes** button to submit the request, -or **Cancel** to return without making any changes. - -The list of configured dependencies, and the status of each one, is shown in the -merge request widget: - - - -Until all dependencies have, themselves, been merged, the **Merge** -button is disabled for the dependent merge request. In -particular, note that **closed merge requests** still prevent their -dependents from being merged - it is impossible to automatically -determine whether the dependency expressed by a closed merge request -has been satisfied in some other way or not. - -If a merge request has been closed **and** the dependency is no longer relevant, -it must be removed as a dependency, following the instructions above, before -merge. - -## Limitations - -- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551) -- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549) -- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) - -The last item merits a little more explanation. Dependencies between merge -requests can be described as a graph of relationships. The simplest possible -graph has one merge request that depends upon another: - -```mermaid -graph LR; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; -``` - -A more complex (and still supported) graph might have one merge request that -directly depends upon several others: - -```mermaid -graph LR; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; - herfriend/another-lib!1-->mycorp/awesome-project!100; -``` - -Several different merge requests can also directly depend upon the -same merge request: - -```mermaid -graph LR; - herfriend/another-lib!1-->myfriend/awesome-lib!10; - herfriend/another-lib!1-->mycorp/awesome-project!100; -``` - -What is **not** supported is a "deep", or "nested" graph of dependencies. For example: - -```mermaid -graph LR; - herfriend/another-lib!1-->myfriend/awesome-lib!10; - myfriend/awesome-lib!10-->mycorp/awesome-project!100; -``` - -In this example, `myfriend/awesome-lib!10` depends on `herfriend/another-lib!1`, -and is itself a dependent of `mycorp/awesome-project!100`. This means that -`myfriend/awesome-lib!10` becomes an **indirect** dependency of -`mycorp/awesome-project!100`, which is not yet supported. +<!-- This redirect file can be deleted after <2022-11-22>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 9182cf11566..57c4ff455cb 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -7,125 +7,143 @@ type: reference, concepts # Merge when pipeline succeeds **(FREE)** -When reviewing a merge request that looks ready to merge but still has a -pipeline running, you can set it to merge automatically when the -pipeline succeeds. This way, you don't have to wait for the pipeline to -finish and remember to merge the request manually. +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 +have to remember later to merge the work manually: - + -## How it works +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: -When you select "Merge When Pipeline Succeeds", the status of the merge -request is updated to show the impending merge. If you can't wait -for the pipeline to succeed, you can choose **Merge immediately** -in the dropdown menu on the right of the main button. +- 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 + to ensure the new changes are reviewed before merge. -The author of the merge request and project members with the Developer role can -cancel the automatic merge at any time before the pipeline finishes. +## Set a merge request to MWPS - +Prerequisites: -When the pipeline succeeds, the merge request is automatically merged. -When the pipeline fails, the author gets a chance to retry any failed jobs, -or to push new commits to fix the failure. +- 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). +- The merge request must have received all required approvals. -When the jobs are retried and succeed on the second try, the merge request -is automatically merged. When the merge request is updated with -new commits, the automatic merge is canceled to allow the new -changes to be reviewed. +To do this when pushing from the command line, use the `merge_request.merge_when_pipeline_succeeds` +[push option](../push_options.md). -By default, all threads must be resolved before you see the **Merge when -pipeline succeeds** button. If someone adds a new comment after -the button is selected, but before the jobs in the CI pipeline are -complete, the merge is blocked until you resolve all existing threads. +To do this from the GitLab user interface: -## Only allow merge requests to be merged if the pipeline succeeds +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **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**. -You can prevent merge requests from being merged if: +If a new comment is added to the merge request after you select **Merge when pipeline succeeds**, +but before the pipeline completes, GitLab blocks the merge until you +resolve all existing threads. -- No pipeline ran. -- The pipeline did not succeed. +## Cancel an auto-merge -This works for both: +If a merge request is set to MWPS, you can cancel it. -- GitLab CI/CD pipelines -- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations) +Prerequisites: + +- You must either be the author of the merge request, or a project member with + at least the Developer role. +- The merge request's pipeline must still be in progress. + +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. Scroll to the merge request reports section. +1. Select **Cancel auto-merge**. + + + +## Require a successful pipeline for merge + +You can configure your project to require a complete and successful pipeline before +merge. This configuration works for both: + +- GitLab CI/CD pipelines. +- Pipelines run from an [external CI integration](../integrations/index.md#available-integrations). As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md) -does not disable this feature, as it is possible to use pipelines from external -CI providers with this feature. To enable it, you must: +does not disable this feature, but you can use pipelines from external +CI providers with it. + +Prerequisites: + +- Ensure CI/CD is configured to run a pipeline for every merge request. +- You must have at least the Maintainer role in the project. + +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. 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). +1. Select **Save**. + +### Allow merge after skipped pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. + +When the **Pipelines must succeed** checkbox is checked, +[skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent +merge requests from being merged. + +Prerequisite: -1. On the top bar, select **Menu > Projects** and find your project. +- You must have at least the Maintainer role in the project. + +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. Under **Merge checks**, select the **Pipelines must succeed** checkbox. +1. Under **Merge checks**: + - Select **Pipelines must succeed**. + - Select **Skipped pipelines are considered successful**. 1. Select **Save**. -This setting also prevents merge requests from being merged if there is no pipeline. -You should be careful to configure CI/CD so that pipelines run for every merge request. +## Troubleshooting -### Limitations +### Merge requests don't merge when successful pipeline is required -When this setting is enabled, a merge request is prevented from being merged if there -is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/index.md#only--except) -or [`rules`](../../../ci/yaml/index.md#rules) are used and they don't generate any pipelines. +If you require a successful pipeline for a merge, this setting can conflict with some +use cases that do not generate pipelines, such as [`only/except`](../../../ci/yaml/index.md#only--except) +or [`rules`](../../../ci/yaml/index.md#rules). Ensure your project +[runs a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) for +every merge request, and that the pipeline is successful. -You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) -and that it's successful. +### Ensure test parity between pipeline types -If both a branch pipeline and a merge request pipeline are triggered for a single -merge request, only the success or failure of the *merge request pipeline* is checked. -If the merge request pipeline is configured with fewer jobs than the branch pipeline, -it could allow code that fails tests to be merged: +If a merge request triggers both a branch pipeline and a merge request pipeline, +the success or failure of only the *merge request pipeline* is checked. +If the merge request pipeline contains fewer jobs than the branch pipeline, +it could allow code that fails tests to be merged, like in this example: ```yaml branch-pipeline-job: rules: - if: $CI_PIPELINE_SOURCE == "push" script: - - echo "Code testing scripts here, for example." + - echo "Testing happens here." merge-request-pipeline-job: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" script: - - echo "No tests run, but this pipeline always succeeds and enables merge." + - echo "No testing happens here. This pipeline always succeeds, and enables merge." - echo true ``` -You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines) -for details on avoiding two pipelines for a single merge request. - -### Skipped pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. - -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent -merge requests from being merged. To change this behavior: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. -1. Under **Merge checks**: - - Ensure **Pipelines must succeed** is selected. - - Select the **Skipped pipelines are considered successful** checkbox. -1. Select **Save**. - -## From the command line - -You can use [Push Options](../push_options.md) to enable merge when pipeline succeeds -for a merge request when pushing from the command line. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +Instead, use branch (`push`) pipelines or merge request pipelines, when possible. +For details on avoiding two pipelines for a single merge request, read the +[`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines). diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index c4e4b40dc48..68dd6477408 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -12,9 +12,8 @@ merge requests are merged into an existing branch. ## Configure a project's merge method -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge method** section, select your desired merge method. 1. Select **Save changes**. @@ -110,7 +109,7 @@ gitGraph ``` This method is equivalent to `git merge --ff <source-branch>` for regular merges, and to -`git merge -squash <source-branch>` for squash merges. +`git merge --squash <source-branch>` for squash merges. When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 8f433c13887..a6e0740ff78 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -6,50 +6,86 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Revert changes **(FREE)** -You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") -by clicking the **Revert** button in merge requests and commit details. +You can revert individual commits or an entire merge request in GitLab. +When you revert a commit in Git, you create a new commit that reverses all actions +taken in the original commit: + +- Lines added in the original commit are removed. +- Lines removed in the original commit are added back. +- Lines modified in the original commit are restored to their previous state. + +Your **revert commit** is still subject to your project's access controls and processes. ## Revert a merge request -NOTE: -The **Revert** button is shown only for projects that use the -merge method "Merge Commit", which can be set under the project's -**Settings > General > Merge request**. [Fast-forward commits](methods/index.md#fast-forward-merge) -can not be reverted by using the merge request view. +After a merge request is merged, you can revert all changes in the merge request. + +Prerequisites: -After the merge request has been merged, use the **Revert** button -to revert the changes introduced by that merge request. +- You must have a role in the project that allows you to edit merge requests, and add + code to the repository. +- Your project must use the [merge method](methods/index.md#fast-forward-merge) **Merge Commit**, + which is set in the project's **Settings > General > Merge request**. You can't revert + fast-forwarded commits from the GitLab UI. - +To do this: -After you select that button, a modal appears where you can choose to -revert the changes directly into the selected branch or you can opt to -create a new merge request with the revert changes. +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. Scroll to the merge request reports area, and find the report showing when the + merge request was merged. +1. Select **Revert**. +1. In **Revert in branch**, select the branch to revert your changes into. +1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. +1. Select **Revert**. -After the merge request has been reverted, the **Revert** button is no longer available. +The option to **Revert** is no longer shown after a merge request is reverted. ## Revert a commit -You can revert a commit from the commit details page: +You can revert any commit in a repository into either: + +- The current branch. +- A new merge request. + +Prerequisites: + +- You must have a role in the project that allows you to edit merge requests, and add + code to the repository. + +To do this: + +1. On the top bar, select **Main menu > Projects** and 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 **Commits**, then select the title of the commit 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 the title of the commit to display full information about the commit. +1. In the top right corner, select **Options**, then select **Revert**. +1. In **Revert in branch**, select the branch to revert your changes into. +1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. +1. Select **Revert**. + +The option to **Revert** is no longer shown after a commit is reverted. - +### Revert a merge commit to a different parent commit -Similar to reverting a merge request, you can opt to revert the changes -directly into the target branch or create a new merge request to revert the -changes. +When you revert a merge commit, the branch you merged to (usually `main`) is always the +first parent. To revert a merge commit to a different parent, +you must revert the commit from the command line: -After a commit is reverted, the **Revert** button is no longer available. +1. Identify the SHA of the parent commit you want to revert to. +1. Identify the parent number of the commit you want to revert to. (Defaults to 1, for the first parent.) +1. Modify this command, replacing `2` with the parent number, and `7a39eb0` with the commit SHA: -When reverting merge commits, the mainline is always the -first parent. If you want to use a different mainline, you need to do that -from the command line. + ```shell + git revert -m 2 7a39eb0 + ``` -Here's an example to revert a merge commit using the second parent as the -mainline: +## Related topics -```shell -git revert -m 2 7a39eb0 -``` +- [Official `git revert` documentation](https://git-scm.com/docs/git-revert) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png Binary files differdeleted file mode 100644 index 38e18115803..00000000000 --- a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_3.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png Binary files differnew file mode 100644 index 00000000000..47b7be3886d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_summary_comment_v15_4.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 27b223c48ec..78f82b019b8 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -56,12 +56,11 @@ displays next to your name. You can submit your completed review in multiple ways: - Use the `/submit_review` [quick action](../../quick_actions.md) in the text of a non-review comment. -- Select **Finish review** and then **Submit review** in the footer at the bottom of the screen. +- Select **Finish review**, then select **Submit review** at the bottom of the modal window. + In the modal window, you can supply a **Summary comment**, approve the merge request, and + include quick actions: -Selecting **Finish review** opens a modal window to add an optional comment to summarize your review. -You can also include quick actions: - - +  When you submit your review, GitLab: @@ -69,6 +68,7 @@ When you submit your review, GitLab: - Sends a single email to every notifiable user of the merge request, with your review comments attached. Replying to this email creates a new comment on the merge request. - Perform any quick actions you added to your review comments. +- Optional. Approves the merge request. ### Resolve or unresolve thread with a comment @@ -96,7 +96,7 @@ 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 removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. +> - [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) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 7e37990b9bf..066149afbb5 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -60,9 +60,8 @@ squash the commits as part of the merge process: To configure the default squashing behavior for all merge requests in your project: -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge requests**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. 1. In the **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 0d7794a3ebd..da705a53153 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -1,5 +1,5 @@ --- -stage: Manage +stage: Govern group: Compliance info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts @@ -61,9 +61,8 @@ using the API. You don't need to wait for a merge request webhook payload to be Within each project's settings, you can see a list of status checks added to the project: -1. In your project, go to **Settings > General**. -1. Expand the **Merge requests** section. -1. Scroll down to the **Status checks** sub-section. +1. In your project, go to **Settings > Merge requests** section. +1. Scroll down to **Status checks**.  diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index ef734225fb4..723ca17ee56 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -37,27 +37,75 @@ For information about project and group milestones API, see: To view the milestone list: -1. On the top bar, select **Menu > Projects** and find your project or - **Menu > Groups** and find your group. +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**. 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. -NOTE: +### View milestones in a project with issues turned off + If a project has issue tracking [turned off](../settings/index.md#configure-project-visibility-features-and-permissions), you can get to the milestones page -by going to its URL. To do so, add: `/-/milestones` to your project or group URL. -For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/milestones`. -This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). +by going to its URL. + +To do so: + +1. Go to your project. +1. Add: `/-/milestones` to your project URL. + For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/milestones`. + +Alternatively, this project's issues are visible in the group's milestone page. + +Improving this experience is tracked in issue [339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). ### View all milestones You can view all the milestones you have access to in the entire GitLab namespace. You might not see some milestones because they're in projects or groups you're not a member of. -To do so, on the top bar select **Menu > Milestones**. +To do so, on the top bar select **Main menu > Milestones**. + +### View milestone details + +To view more information about a milestone, +in the milestone list select the title of the milestone you want to view. + +The milestone view shows the title and description. + +There are also tabs below these that show the following: + +- **Issues**: Shows all issues assigned to the milestone. These are displayed in three columns named: + - Unstarted Issues (open and unassigned) + - Ongoing Issues (open and assigned) + - Completed Issues (closed) +- **Merge Requests**: Shows all merge requests assigned to the milestone. These are displayed in four columns named: + - Work in progress (open and unassigned) + - Waiting for merge (open and assigned) + - Rejected (closed) + - Merged +- **Participants**: Shows all assignees of issues assigned to the milestone. +- **Labels**: Shows all labels that are used in issues assigned to the milestone. + +#### Burndown charts + +The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), +showing the progress of completing a milestone. + + + +#### Milestone sidebar + +The milestone sidebar on the milestone view shows the following: + +- Percentage complete, which is calculated as number of closed issues divided by total number of issues. +- The start date and due date. +- The total time spent on all issues and merge requests assigned to the milestone. +- The total issue weight of all issues assigned to the milestone. + + ## Create a milestone @@ -71,7 +119,7 @@ Prerequisites: To create a milestone: -1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +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. Select **New milestone**. 1. Enter the title. @@ -90,7 +138,7 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. 1. Select **Edit**. 1. Edit the title, start date, due date, or description. @@ -106,7 +154,7 @@ Prerequisites: To edit a milestone: -1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Projects** and find your project or **Main menu > Groups** and find your group. 1. Select a milestone's title. 1. Select **Delete**. 1. Select **Delete milestone**. @@ -131,7 +179,7 @@ Prerequisites: To promote a project milestone: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Either: - Select **Promote to Group Milestone** (**{level-up}**). - Select the milestone title, and then select **Promote**. @@ -153,13 +201,13 @@ To assign or unassign a milestone: You can also use the `/assign` [quick action](../quick_actions.md) in a comment. -## Filtering issues and merge requests by milestone +## Filter issues and merge requests by milestone -### Filtering in list pages +### Filters in list pages From the project and group issue/merge request list pages, you can filter by both group and project milestones. -### Filtering in issue boards +### Filters in issue boards From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in: @@ -181,42 +229,6 @@ When filtering by milestone, in addition to choosing a specific project mileston - **Upcoming**: Show issues or merge requests that have been assigned the open milestone and has the nearest due date in the future. - **Started**: Show issues or merge requests that have an open assigned milestone with a start date that is before today. -## Milestone view - -The milestone view shows the title and description. - -There are also tabs below these that show the following: - -- **Issues**: Shows all issues assigned to the milestone. These are displayed in three columns named: - - Unstarted Issues (open and unassigned) - - Ongoing Issues (open and assigned) - - Completed Issues (closed) -- **Merge Requests**: Shows all merge requests assigned to the milestone. These are displayed in four columns named: - - Work in progress (open and unassigned) - - Waiting for merge (open and assigned) - - Rejected (closed) - - Merged -- **Participants**: Shows all assignees of issues assigned to the milestone. -- **Labels**: Shows all labels that are used in issues assigned to the milestone. - -### Burndown Charts - -The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), -showing the progress of completing a milestone. - - - -### Milestone sidebar - -The milestone sidebar on the milestone view shows the following: - -- Percentage complete, which is calculated as number of closed issues divided by total number of issues. -- The start date and due date. -- The total time spent on all issues and merge requests assigned to the milestone. -- The total issue weight of all issues assigned to the milestone. - - - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues 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 2c668e2c409..03f8ecac77f 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 @@ -7,17 +7,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Custom domains and SSL/TLS certificates **(FREE)** -Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). -To use one or more custom domain names with your Pages site, you can: +You can use custom domains: -- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain). +- With GitLab Pages. +- To [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). + When using custom domains this way, you use the GitLab Pages feature but can skip the [requirements](#requirements). + +To use one or more custom domain names: + +- Add a [custom **root domain** or a **subdomain**](#set-up-a-custom-domain). - Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages). -## Set up Pages with a custom domain +## Set up a custom domain -To set up Pages with a custom domain name, read the requirements -and steps below. +To set up Pages with a custom domain name, read the requirements and steps below. ### Requirements @@ -45,7 +50,7 @@ and steps below. Follow the steps below to add your custom domain to Pages. See also this document for an [overview on DNS records](dns_concepts.md). -#### 1. Add a custom domain to Pages +#### 1. Add a custom domain Navigate to your project's **Setting > Pages** and select **+ New domain** to add your custom domain to GitLab Pages. You can choose whether to: @@ -64,7 +69,7 @@ and paste them in your domain's control panel as a `TXT` record on the next step  -#### 3. Set up DNS records for Pages +#### 3. Set up DNS records Read this document for an [overview of DNS records for Pages](dns_concepts.md). If you're familiar with the subject, follow the instructions below @@ -144,7 +149,7 @@ They require: | `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | If you're using Cloudflare, check -[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). +[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirect-wwwdomaincom-to-domaincom-with-cloudflare). > **Notes**: > @@ -186,7 +191,7 @@ from the GitLab project. in place. Your domain is periodically reverified, and may be disabled if the record is removed. -##### Troubleshooting Pages domain verification +##### Troubleshoot domain verification To manually verify that you have properly configured the domain verification `TXT` DNS entry, you can run the following command in your terminal: @@ -218,7 +223,7 @@ For a subdomain: | `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | | `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -### Adding more domain aliases +### Add more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. An alias can be understood as having many doors leading to the same room. @@ -226,7 +231,7 @@ An alias can be understood as having many doors leading to the same room. All the aliases you've set to your site are listed on **Setting > Pages**. From that page, you can view, add, and remove them. -### Redirecting `www.domain.com` to `domain.com` with Cloudflare +### Redirect `www.domain.com` to `domain.com` with Cloudflare If you use Cloudflare, you can redirect `www` to `domain.com` without adding both `www.domain.com` and `domain.com` to GitLab. 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 0cc6cb808d1..b5487f7a465 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 @@ -30,7 +30,7 @@ Before you can enable automatic provisioning of an SSL certificate for your doma - Acquired a domain (`example.com`) and added a [DNS entry](index.md) pointing it to your Pages website. The top-level domain (`.com`) must be a [public suffix](https://publicsuffix.org/). -- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) +- [Added your domain to your Pages project](index.md#1-add-a-custom-domain) and verified your ownership. - Verified your website is up and running, accessible through your custom domain. @@ -76,7 +76,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. 1. Make sure your domain **doesn't have** an `AAAA` DNS record. 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain-to-pages). + 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). 1. Go to step 1. ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour @@ -85,7 +85,7 @@ If you've enabled Let's Encrypt integration, but a certificate is absent after a 1. Go to your project's **Settings > Pages**. 1. Select **Remove** on your domain. -1. [Add the domain again and verify it](index.md#1-add-a-custom-domain-to-pages). +1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). 1. If you still see the same message after some time: 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 510f9332e7b..58e15104815 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -16,7 +16,7 @@ Use a `.gitlab-ci.yml` template when you have an existing project that you want Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may have to do additional configuration for the Pages site to generate properly. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select the project's name. 1. From the **Add** (**{plus}**) dropdown, select **New file**. 1. From the **Select a template type** dropdown, select `.gitlab-ci.yml`. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 68a2a6a80ad..1c3d5d722cb 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -266,6 +266,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production ``` Now add another job to the CI file, telling it to @@ -289,6 +290,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -342,6 +344,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -386,6 +389,7 @@ pages: - public rules: - if: $CI_COMMIT_BRANCH == "main" + environment: production test: stage: test @@ -420,7 +424,7 @@ Now GitLab CI/CD not only builds the website, but also: For more information, see the following blog posts. -- Use GitLab CI/CD `environments` to +- Use GitLab CI/CD `environments` to [deploy your web app to staging and production](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). - Learn how to run jobs [sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md new file mode 100644 index 00000000000..7e618fbaec8 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -0,0 +1,58 @@ +--- +stage: Create +group: Incubation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Tutorial: Use the GitLab UI to deploy your static site **(FREE)** + +This tutorial assumes you have a project that either: + +- Generates static sites or a client-rendered single-page application (SPA), + such as [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). +- Contains a framework configured for static output, such as [Next.js](https://nextjs.org), + [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). + +## Update your app to output files to the `public` folder + +GitLab Pages requires all files intended to be part of the published website to +be in a root-level folder called `public`. If you create this folder during the build +pipeline, committing it to Git is not required. + +For detailed instructions, read [Configure the public files folder](../public_folder.md). + +## Set up the `.gitlab-ci.yml` file + +GitLab helps you write the `.gitlab-ci.yml` needed to create your first GitLab Pages +deployment pipeline. Rather than building the file from scratch, it asks you to +provide the build commands, and creates the necessary boilerplate for you. + +To build your YAML file from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages** to display the friendly + interface **Get Started With Pages**. +1. If your framework's build process does not need one of the provided build + commands, you can either: + - Skip the step by selecting **Next**. + - Enter `:` (the bash "do nothing" command) if you still want to incorporate that + step's boilerplate into your `.gitlab-ci.yml` file. +1. Optional. Edit and adjust the generated `.gitlab-ci.yml` file as needed. +1. Commit your `.gitlab-ci.yml` to your repository. This commit triggers your first + GitLab Pages deployment. + +## Troubleshooting + +### If you can't see the "Get Started with Pages" interface + +GitLab doesn't show this interface if you have either: + +- Deployed a GitLab Pages site before. +- Committed a `.gitlab-ci.yml` through this interface at least once. + +To fix this problem: + +- If you see the message **Waiting for the Pages Pipeline to complete**, select + **Start over** to start the wizard again. +- If your project has previously deployed GitLab Pages successfully, + [manually update](pages_from_scratch.md) your `.gitlab-ci.yml`. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index af49522efe2..1f3628b74ec 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -38,12 +38,13 @@ Learn more about To create a GitLab Pages website: -| Document | Description | -|----------|-------------| +| Document | Description | +|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------| +| [Use the GitLab UI to create a simple `.gitlab-ci.yml`](getting_started/pages_ui.md) | Add a Pages site to an existing project. Use the UI to set up a simple `.gitlab-ci.yml`. | | [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | -| [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | -| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | -| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | +| [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | +| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | +| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | To update a GitLab Pages website: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 3bd16a17f23..da024881ed6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -314,6 +314,7 @@ pages: artifacts: paths: - public + environment: production ``` The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/configure_runners.md#artifact-and-cache-settings). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md new file mode 100644 index 00000000000..f9c80875cc9 --- /dev/null +++ b/doc/user/project/pages/public_folder.md @@ -0,0 +1,153 @@ +--- +description: 'Learn how to configure the build output folder for the most +common static site generators' +stage: Create +group: Incubation +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Configure the public files folder **(FREE)** + +GitLab Pages requires all files you intend to be available in the published website to +be in a root-level folder called `public`. This page describe how +to set this up for some common static site generators. + +## Guide by framework + +### Eleventy + +For Eleventy, you should either: + +1. Add the `--output=public` flag in Eleventy's build commands, for example: + + `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` + +1. Add the following to your `.eleventy.js` file: + + ```javascript + // .eleventy.js + module.exports = function(eleventyConfig) { + return { + dir: { + output: "public" + } + } + }; + ``` + +### Astro + +By default, Astro uses the `public` folder to store static assets. For GitLab Pages, +rename that folder to a collision-free alternative first: + +1. In your project directory, run: + + ```shell + mv public static + ``` + +1. Add the following to your `astro.config.mjs`. This code informs Astro about + our folder name remapping: + + ```javascript + // astro.config.mjs + export default { + // GitLab Pages requires exposed files to be located in a folder called "public". + // So we're instructing Astro to put the static build output in a folder of that name. + dist: 'public', + + // The folder name Astro uses for static files (`public`) is already reserved + // for the build output. So in deviation from the defaults we're using a folder + // called `static` instead. + public: 'static', + }; + ``` + +### SvelteKit + +NOTE: +GitLab Pages supports only static sites. For SvelteKit, +we recommend using [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). + +When using `adapter-static`, add the following to your `svelte.config.js`: + +```javascript +// svelte.config.js +import adapter from '@sveltejs/adapter-static'; + +export default { + kit: { + adapter: adapter({ + pages: 'public' + }) + } +}; +``` + +### Next.js + +NOTE: +GitLab Pages supports only static sites. For Next.js, we +recommend using Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export) + +Use the `-o public` flag after `next export` as the build command, for +example: + +```shell +next export -o public +``` + +### Nuxt.js + +NOTE: +GitLab Pages supports only static sites. + +1. Add the following to your `nuxt.config.js`: + + ```javascript + export default { + target: 'static', + generate: { + dir: 'public' + } + } + ``` + +1. Configure your Nuxt.js application for + [Static Site Generation](https://nuxtjs.org/docs/features/deployment-targets#static-hosting). + +### Vite + +Update your `vite.config.js` to include the following: + +```javascript +// vite.config.js +export default { + build: { + outDir: 'public' + } +} +``` + +### Webpack + +Update your `webpack.config.js` to include the following: + +```javascript +// webpack.config.js +module.exports = { + output: { + path: __dirname + '/public' + } +}; +``` + +## Should you commit the `public` folder? + +Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks +for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. So +If you set up a job that creates the `public` folder before deploy, such as by +running `npm run build`, committing the folder isn't required. + +If you prefer to build your site locally, you can commit the `public` folder and +omit the build step during the job, instead. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 3e40a7962ae..9b685592c9d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -41,7 +41,7 @@ Prerequisite: To protect a branch: -1. On the top bar, select **Menu > Projects** and find your project. +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. @@ -63,7 +63,7 @@ Prerequisite: To protect multiple branches at the same time: -1. On the top bar, select **Menu > Projects** and find your project. +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, type the branch name and a wildcard. @@ -96,7 +96,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Branches**. 1. Select **New branch**. 1. Fill in the branch name and select an existing branch, tag, or commit to @@ -109,7 +109,7 @@ 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 **Menu > Projects** and find your project. +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. @@ -125,7 +125,7 @@ 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 **Menu > Projects** and find your project. +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. @@ -153,7 +153,7 @@ Prerequisites: To allow a deploy key to push to a protected branch: -1. On the top bar, select **Menu > Projects** and find your project. +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. @@ -172,7 +172,7 @@ protected branches. To protect a new branch and enable force push: -1. On the top bar, select **Menu > Projects** and find your project. +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. @@ -184,7 +184,7 @@ 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 **Menu > Projects** and find your project. +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. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. @@ -200,7 +200,7 @@ For a protected branch, you can require at least one approval by a [Code Owner]( To protect a new branch and enable Code Owner's approval: -1. On the top bar, select **Menu > Projects** and find your project. +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. @@ -210,7 +210,7 @@ To protect a new branch and enable Code Owner's approval: To enable Code Owner's approval on branches that are already protected: -1. On the top bar, select **Menu > Projects** and find your project. +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. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. @@ -242,7 +242,7 @@ for details about the pipelines security model. Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, type the branch name. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 870c544cf4c..9b1e862af58 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -97,7 +97,7 @@ Prerequisite: To do this: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > 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 d02609cbdc7..3eb333f5785 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -102,7 +102,7 @@ long Git commands. ### Merge when pipeline succeeds alias -To set up a Git alias for the +To set up a Git alias for the [merge when pipeline succeeds Git push option](#push-options-for-merge-requests): ```shell diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 216d040734d..8b8eba62cce 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -67,7 +67,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | | `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | -| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the [draft status](merge_requests/drafts.md). | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. Also, mark both as related. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | @@ -100,7 +100,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | | `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | @@ -110,6 +110,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/timeline <timeline comment> \| <date(YYYY-MM-DD)> <time(HH:MM)>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a timeline event to this incident. For example, `/timeline DB load spiked \| 2022-09-07 09:30`. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368721) in GitLab 15.4). | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | | `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | @@ -121,7 +122,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | | `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | +| `/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).| ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index d3456e086ce..87ea95524fe 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -57,8 +57,6 @@ switch between ascending or descending order, select **Sort order**. ## Create a release -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. - You can create a release: - [Using a job in your CI/CD pipeline](#creating-a-release-by-using-a-cicd-job). @@ -68,16 +66,16 @@ You can create a release: We recommend creating a release as one of the last steps in your CI/CD pipeline. +### Create a release in the Releases page + Prerequisites: - You must have at least the Developer role for a project. For more information, read [Release permissions](#release-permissions). -### Create a release in the Releases page - To create a release in the Releases page: -1. On the top bar, select **Menu > Projects** and find your project. +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. From the [**Tag name**](release_fields.md#tag-name) dropdown, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release @@ -99,7 +97,7 @@ To create a release in the Tags page, add release notes to either an existing or To add release notes to a new Git tag: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Select **New tag**. 1. Optional. Enter a tag message in the **Message** text box. @@ -109,7 +107,7 @@ To add release notes to a new Git tag: To edit release notes of an existing Git tag: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Tags**. 1. Select **Edit release notes** (**{pencil}**). 1. In the **Release notes** text box, enter the release's description. @@ -124,8 +122,11 @@ You can create a release directly as part of the GitLab CI/CD pipeline by using The release is created only if the job processes without error. If the API returns an error during release creation, the release job fails. -For examples of how you can create a release of your application in the CI/CD pipeline, -see [Release CI/CD examples](release_cicd_examples.md). +Methods for creating a release using a CI/CD job include: + +- [Create a release when a Git tag is created](release_cicd_examples.md#create-a-release-when-a-git-tag-is-created). +- [Create a release when a commit is merged to the default branch](release_cicd_examples.md#create-a-release-when-a-commit-is-merged-to-the-default-branch). +- [Create release metadata in a custom script](release_cicd_examples.md#create-release-metadata-in-a-custom-script). ### Use a custom SSL CA certificate authority @@ -232,7 +233,7 @@ Prerequisites: To delete a release in the UI: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. @@ -312,6 +313,7 @@ deploy_to_production: script: deploy_to_prod.sh rules: - if: $CI_DEPLOY_FREEZE == null + environment: production ``` To set a deploy freeze window in the UI, complete these steps: diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index f1d3e55a707..bfd83a20caf 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -12,9 +12,13 @@ CI/CD pipeline. ## Create a release when a Git tag is created -In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers -the release. You can use this method if you prefer to create the Git tag manually, and create a -release as a result. +In this CI/CD example, the release is triggered by one of the following events: + +- Pushing a Git tag to the repository. +- Creating a Git tag in the UI. + +You can use this method if you prefer to create the Git tag manually, and create a release as a +result. NOTE: Do not provide Release notes when you create the Git tag in the UI. Providing release notes @@ -40,8 +44,8 @@ release_job: ## Create a release when a commit is merged to the default branch -In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use -this method if your release workflow does not create a tag manually. +In this CI/CD example, the release is triggered when you merge a commit to the default branch. You +can use this method if your release workflow does not create a tag manually. Key points in the following _extract_ of an example `.gitlab-ci.yml` file: @@ -69,16 +73,75 @@ Environment variables set in `before_script` or `script` are not available for e in the same job. Read more about [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). +## Create release metadata in a custom script + +In this CI/CD example the release preparation is split into separate jobs for greater flexibility: + +- The `prepare_job` job generates the release metadata. Any image can be used to run the job, + including a custom image. The generated metadata is stored in the variable file `variables.env`. + This metadata is [passed to the downstream job](../../../ci/variables/index.md#pass-an-environment-variable-to-another-job). +- The `release_job` uses the content from the variables file to create a release, using the + metadata passed to it in the variables file. This job must use the + `registry.gitlab.com/gitlab-org/release-cli:latest` image because it contains the release CLI. + +```yaml +prepare_job: + stage: prepare # This stage must run before the release stage + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables + - echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file + artifacts: + reports: + dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs + +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + needs: + - job: prepare_job + artifacts: true + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "running release_job for $TAG" + release: + name: 'Release $TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG + tag_name: '$TAG' # variables must be defined elsewhere + ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the + milestones: # prepare_job + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + ## Skip multiple pipelines when creating a release Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows: - Tag first, release second: + 1. A tag is created via UI or pushed. 1. A tag pipeline is triggered, and runs `release` job. 1. A release is created. - Release first, tag second: + 1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs `release` job. 1. A release is created. 1. A tag is created. diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 9e65ab4bc01..90363fca8b0 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -46,7 +46,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av Or from the GitLab Package Registry: ```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-darwin-amd64" + 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" ``` 1. Give it permissions to execute: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 3083ca5da3c..d31c64f4640 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -64,7 +64,7 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. @@ -115,7 +115,7 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). @@ -132,7 +132,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or higher](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 **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand the **Default branch** section. 1. Clear the **Allow owners to manage default branch protection per group** checkbox. @@ -152,7 +152,7 @@ can be overridden on a per-group basis by the group's owner. In [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 6da2e5fc7ee..5e5a42a061b 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -59,7 +59,8 @@ To compare branches in a repository:  This feature allows merged branches to be deleted in bulk. Only branches that -have been merged and [are not protected](../../protected_branches.md) are deleted as part of +have been merged into the project's default branch and +[are not protected](../../protected_branches.md) are deleted as part of this operation. It's particularly useful to clean up old branches that were not deleted diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index b2a6c8848ce..d307a6a8580 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -193,10 +193,10 @@ you can sign individual commits manually, or configure Git to default to signed 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 **Menu > Projects** and find your project. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Commits**. 1. To review commits for a merge request: - 1. On the top bar, select **Menu > Projects** and find your project. + 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. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 8e1286548b9..4926cf3812e 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -49,7 +49,7 @@ to a branch in the repository. When you use the command line, you can commit mul on their respective thread. - **Cherry-pick a commit:** In GitLab, you can - [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-pick-a-single-commit) from the UI. - **Revert a commit:** [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) @@ -201,6 +201,14 @@ To render an OpenAPI file: ## Repository size +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368150) in GitLab 15.3, feature flags `gitaly_revlist_for_repo_size` and `gitaly_catfile_repo_size` for alternative repository size calculations. + +FLAG: +On self-managed GitLab, by default GitLab uses the `du -sk` command to determine the size of a repository. GitLab can use either +`git-rev-list` (enabled with feature flag `gitaly_revlist_for_repo_size`) or `git-cat-file` (enabled with feature flag +`gitaly_catfile_repo_size`) instead. To switch between different calculation methods, ask an administrator to +[enable or disable](../../../administration/feature_flags.md) these feature flags. + The **Project information** page shows the size of all files in the repository. The size is updated, at most, every 15 minutes. The file size includes repository files, artifacts, and LFS. diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index ba425ae3dc7..d2ca49c118c 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -10,13 +10,13 @@ description: "Documentation on large repositories." GitLab, like any Git based system, is subject to similar performance restraints when it comes to large repositories that size into the gigabytes. -On this page we detail several best practices to improve performance with these large repositories on GitLab. +In the following sections, we detail several best practices for improving performance with these large repositories on GitLab. ## Large File System (LFS) -It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, graphics, etc.) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. +It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, or graphics) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. -To analyze if the repository has these sorts of objects, it's recommended to run [`git-sizer`](https://github.com/github/git-sizer) to get a detailed analysis. This tool shows in detail what makes up the repository as well as highlights any areas of concern. +To analyze if the repository has these sorts of objects, it's recommended to run a tool like [`git-sizer`](https://github.com/github/git-sizer) to get a detailed analysis. These tools can show in detail what makes up the repository as well as highlights any areas of concern. If any large objects are found, it's then recommended removing them with tools such as [`git filter-repo`](reducing_the_repo_size_using_git.md). Refer to the [Git LFS documentation for more information](../../../topics/git/lfs/index.md). diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 340d7b48a47..793ca2a5f1f 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -45,7 +45,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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index b08530c34b3..176461aeba7 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -41,7 +41,7 @@ Prerequisite: - 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original @@ -89,7 +89,7 @@ Prerequisite: - You must have at least the Maintainer role for the project. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories** and identify the mirror to update. @@ -141,7 +141,7 @@ When you mirror a repository and select the **SSH public key** as your authentication method, GitLab generates a public key for you. The non-GitLab server needs this key to establish trust with your GitLab repository. To copy your SSH public key: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Scroll to **Mirrored repositories**. @@ -249,7 +249,7 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. If no repository owner is specified, delete and add the URL again in this format, diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index d0f2b9a8088..159580dcfa5 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -61,7 +61,7 @@ Prerequisite: with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter the **Git repository URL**. Include the username diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index c00ebf415c9..10bdc54ecee 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -33,7 +33,7 @@ section. To set up push mirroring for an existing project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a repository URL. diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 46a9585604e..90d2fdb89d0 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -36,7 +36,7 @@ Prerequisite: To create global push rules: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Push Rules**. 1. Expand **Push rules**. 1. Set the rule you want. @@ -48,7 +48,7 @@ The push rule of an individual project overrides the global push rule. To override global push rules for a specific project, or to update the rules for an existing project to match new global push rules: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Push rules**. 1. Set the rule you want. 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 344c288b607..f209c7ef137 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 @@ -46,7 +46,7 @@ To purge files from a GitLab repository: [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. -1. Generate a fresh +1. Generate a fresh [export from the project](../settings/import_export.md#export-a-project-and-its-data) and download it. This project export contains a backup copy of your repository *and* refs we can use to purge files from your repository. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index f32035102bb..bafa2005fdf 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -150,7 +150,7 @@ The templates are inherited. For example, in a project, you can also access temp To use a custom description template with Service Desk: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. [Create a description template](description_templates.md#create-an-issue-template). 1. On the left sidebar, select **Settings > General > Service Desk**. 1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. @@ -164,7 +164,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General > Service Desk**. 1. Enter a new name in **Email display name**. 1. Select **Save Changes**. @@ -358,9 +358,23 @@ to everyone who can view the project. Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user does not count toward the license limit count. +### Moving a Service Desk issue + +Service Desk issues can be moved like any other issue in GitLab. + +You can move a Service Desk issue the same way you +[move a regular issue](issues/managing_issues.md#move-an-issue) in GitLab. + +If a Service Desk issue is moved to a different project the customer who created the issue stops receiving emails. + ## Troubleshooting Service Desk ### Emails to Service Desk do not create issues Your emails might be ignored because they contain one of the [email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). + +### Responses to a Service Desk issue do not generate emails + +Your issue might have been moved to a different project. +Moved Service Desk issues do not retain email participants. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 4eeb7c5ba83..375e4a62b86 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -43,7 +43,7 @@ Prerequisites: To export a project and its data, follow these steps: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced**. 1. Select **Export project**. @@ -57,13 +57,34 @@ moved to your configured `uploads_directory`. Every 24 hours, a worker deletes t ### Items that are exported -The following items are exported: +The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) +file lists the items exported and imported when migrating projects using file exports. View this file in the branch +for your version of GitLab to see the list of items relevant to you. For example, +[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). + +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. + +Items that are exported include: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations -- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time - tracking, and other project entities +- Issues + - Issue comments + - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) +- Merge requests + - Merge request diffs + - Merge request comments + - Merge request resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Merge request multiple assignees ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request reviewers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) + - Merge request approvers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) +- Labels +- Milestones +- Snippets +- Time tracking and other project entities - Design Management files and data - LFS objects - Issue boards @@ -73,7 +94,7 @@ The following items are exported: - Group members are exported as project members, as long as the user has the Maintainer role in the exported project's group, or is an administrator -The following items are **not** exported: +Items that are **not** exported include: - [Child pipeline history](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Build traces and artifacts @@ -82,20 +103,11 @@ The following items are **not** exported: - Pipeline triggers - Webhooks - Any encrypted tokens -- Merge Request Approvers and [the number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Repository size limits - Deploy keys allowed to push to protected branches - Secure Files -These content rules also apply to creating projects from templates on the -[group](../../group/custom_project_templates.md) -or [instance](../../admin_area/custom_project_templates.md) -levels, because the same export and import mechanisms are used. - -NOTE: -For more details on the specific data persisted in a project export, see the -[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. - ## Import a project and its data > Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. @@ -166,7 +178,8 @@ Imported users can be mapped by their public email addresses on self-managed ins - Public email addresses are not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) for mapping to work correctly. - For contributions to be mapped correctly, users must be an existing member of the namespace, - or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. + or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original + author and the merge requests, notes, or issues that are owned by the importer. - Imported users are set as [direct members](../members/index.md) in the imported project. @@ -403,5 +416,5 @@ Error adding importer user to Project members. Validation failed: User project bots cannot be added to other groups / projects ``` -To use [Import REST APIs](../../../api/project_import_export.md), +To use [Import REST API](../../../api/project_import_export.md), pass regular user account credentials such as [personal access tokens](../../profile/personal_access_tokens.md). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index b973a0f56d1..5c2118e02cf 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -13,7 +13,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. To display all settings in a section, select **Expand**. 1. Optional. Use the search box to find a setting. @@ -23,7 +23,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, 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. @@ -35,7 +35,7 @@ Use topics to categorize projects and find similar new projects. To assign topics to a project: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings** > **General**. 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. @@ -51,7 +51,7 @@ requirements or needs additional oversight. The label can optionally apply Group owners can create, edit, and delete compliance frameworks: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. @@ -170,7 +170,7 @@ include: # Execute individual project's configuration (if project contains .git When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see -[Enforce scan execution](../../application_security/#enforce-scan-execution). +[Enforce scan execution](../../application_security/index.md#enforce-scan-execution). ### Ensure compliance jobs are always run @@ -214,10 +214,10 @@ Compliance pipelines start on the run of _every_ pipeline in a relevant project. triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. Therefore, in projects with compliance frameworks, we recommend replacing -[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md) with the following: +[parent-child pipelines](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: - Direct [`include`](../../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. -- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/) rather than the parent-child +- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/index.md) rather than the parent-child pipeline feature. This alternative ensures the compliance pipeline does not re-start the parent pipeline. @@ -226,7 +226,7 @@ This alternative ensures the compliance pipeline does not re-start the parent pi To configure visibility, features, and permissions for a project: -1. On the top bar, select **Menu > Projects** and find 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. To change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. @@ -241,17 +241,17 @@ Use the toggles to enable or disable features in the project. | Option | More access limit options | Description | |:---------------------------------|:--------------------------|:--------------| | **Issues** | ✓ | Activates the GitLab issues tracker. | -| **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | +| **Repository** | ✓ | Enables [repository](../repository/index.md) functionality | +| **Merge requests** | ✓ | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | | **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | | **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | | **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images. | -| **Analytics** | ✓ | Enables [analytics](../../analytics/). | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | +| **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | | **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | | **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | -| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | | **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | @@ -286,7 +286,7 @@ 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 **Menu > Projects** and find 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. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. @@ -298,7 +298,7 @@ Prerequisites: - You must be an Owner of the project to disable email notifications related to the project. -1. On the top bar, select **Menu > Projects** and find 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. Clear the **Disable email notifications** checkbox. @@ -339,7 +339,7 @@ other features are read-only. Archived projects are also hidden from project lis To archive a project: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced**. 1. In the **Archive project** section, select **Archive project**. @@ -355,7 +355,7 @@ 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 **Menu > Project**. + 1. On the top bar, select **Main menu > Projects > View all 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. @@ -380,7 +380,7 @@ When you change the repository path, users may experience issues if they push to To rename a repository: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced** section. 1. In the **Change path** text box, edit the path. @@ -402,7 +402,7 @@ Prerequisites: To transfer a project: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced**. 1. Under **Transfer project**, choose the namespace to transfer the project to. @@ -420,7 +420,7 @@ to move any project to any namespace. When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free, the following paid feature data is deleted: - [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked -- [Pipeline subscriptions](../../../ci/pipelines/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) +- [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) and [test cases](../../../ci/test_cases/index.md) are deleted. ## Delete a project @@ -433,7 +433,7 @@ Prerequisite: To delete a project: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced**. 1. In the "Delete project" section, select **Delete project**. @@ -472,7 +472,7 @@ Prerequisites: To immediately delete a project marked for deletion: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced**. 1. In the "Permanently delete project" section, select **Delete project**. @@ -504,7 +504,7 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To remove a fork relationship: -1. On the top bar, select **Menu > Projects** and find 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 **Advanced**. 1. In the **Remove fork relationship** section, select **Remove fork relationship**. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 77a53874777..c9c5efce9b1 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -27,6 +27,13 @@ and [personal access tokens](../../profile/personal_access_tokens.md). In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. +WARNING: +The ability to create project access tokens without expiry was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and is planned for removal in GitLab +16.0. When this ability is removed, existing project access tokens without an expiry are planned to have an expiry added. +The automatic adding of an expiry occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry +occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. + You can use project access tokens: - On GitLab SaaS if you have the Premium license tier or higher. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). @@ -43,11 +50,12 @@ configured for personal access tokens. ## Create a project access token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI. To create a project access token: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Optional. Enter an expiry date for the token. The token expires on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. @@ -62,7 +70,7 @@ 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 **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Next to the project access token to revoke, select **Revoke**. @@ -85,7 +93,7 @@ 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 **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Allow project and group access token creation**. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 971ecf66a3c..522ec962e53 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -170,7 +170,7 @@ The following time units are available: In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 5a4e300a210..2a197c733cf 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -260,7 +260,7 @@ a `main` entry point inside the Web IDE. Live Preview is enabled for all projects on GitLab.com. If you are an administrator of a self-managed GitLab instance, and you want to enable Live Preview: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Scroll to **Web IDE** and select **Expand**:  diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index a3ba5789d39..03838a62d59 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -29,7 +29,7 @@ and higher can edit group wikis. Group wiki repositories can be moved using the To access a group wiki: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and 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> @@ -69,7 +69,7 @@ can enable or disable a group wiki through the group settings. To open group settings: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Scroll to **Wiki** and select one of these options: diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index c7f675417bb..b8924c33b13 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -31,7 +31,7 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se To access a project wiki: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 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> @@ -61,7 +61,7 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. On the top bar, select **Menu**. +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**. @@ -79,7 +79,7 @@ to be used as your wiki's home page. To create it: Users with at least the Developer role can create new wiki pages: -1. On the top bar, select **Menu**. +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**. @@ -142,7 +142,7 @@ may not be able to check out the wiki locally afterward. You need at least the Developer role to edit a wiki page: -1. On the top bar, select **Menu**. +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**. @@ -161,7 +161,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the Developer role to delete a wiki page: -1. On the top bar, select **Menu**. +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**. @@ -174,7 +174,7 @@ You need at least the Developer role to delete a wiki page: You need at least the Developer role to move a wiki page: -1. On the top bar, select **Menu**. +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**. @@ -200,7 +200,7 @@ The history page shows: To view the changes for a wiki page: -1. On the top bar, select **Menu**. +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**. @@ -213,7 +213,7 @@ To view the changes for a wiki page: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. On the top bar, select **Menu**. +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**. @@ -246,7 +246,7 @@ You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. On the top bar, select **Menu**. +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**. @@ -284,7 +284,7 @@ You can disable group wikis from the [group settings](group.md#configure-group-w To add a link to an external wiki from a project's left sidebar: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. @@ -300,7 +300,7 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. In the **Enable integration** section, clear the **Active** checkbox. @@ -310,7 +310,7 @@ To hide the link to an external wiki: To disable a project's internal wiki: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Go to your project and select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 2501fa8b45c..e58bf5aa557 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -11,22 +11,9 @@ code are saved in projects, and most features are in the scope of projects. ## View projects -To explore projects: +To view projects, on the top bar, select **Main menu > Projects > View all projects**. -1. On the top bar, select **Menu > Projects**. -1. Select **Explore projects**. - -The **Projects** page shows a list of projects, sorted by last updated date. - -- To view projects with the most [stars](#star-a-project), select **Most stars**. -- To view projects with the largest number of comments in the past month, select **Trending**. - -NOTE: -The **Explore projects** tab is visible to unauthenticated users unless the -[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted. Then the tab is visible only to signed-in users. - -### Who can view the **Projects** page +### Who can view the Projects page When you select a project, the project landing page shows the project contents. @@ -53,11 +40,16 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec To explore project topics: -1. On the top bar, select **Menu > Projects**. -1. Select **Explore topics**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. Select the **Explore topics** tab. +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 **Projects** page shows list of topics sorted by the number of associated projects. -To view projects associated with a topic, select a topic from the list. +NOTE: +The **Explore projects** tab is visible to unauthenticated users unless the +[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) +is restricted. Then the tab is visible only to signed-in users. You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). @@ -68,8 +60,9 @@ If you're an instance administrator, you can administer all project topics from To create a project in GitLab: -1. On the top bar, select **Menu > Project > Create new project**. -1. On the **Create new project** page, choose if you want to: +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select an option: - Create a [blank project](#create-a-blank-project). - Create a project from a: - [built-in template](#create-a-project-from-a-built-in-template). @@ -88,7 +81,8 @@ To create a project in GitLab: To create a blank project: -1. On the top bar, select **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name of your project. You cannot use special characters at @@ -119,7 +113,8 @@ 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 **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: @@ -145,7 +140,8 @@ 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 **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: @@ -171,7 +167,8 @@ 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 **Menu > Projects > Create new project**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: @@ -210,9 +207,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 **Menu > Projects**. - 1. Select **Groups**. - 1. Select a group. + 1. On the top bar, select **Main menu > Groups** and find your group. 1. Confirm that **New project** is visible in the upper right corner. Contact your GitLab administrator if you require permission. @@ -258,15 +253,13 @@ 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 **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. In the upper right corner of the page, select **Star**. ## View starred projects -1. On the top bar, select **Menu > Projects**. -1. Select **Starred projects**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. Select the **Starred projects** tab. 1. GitLab displays information about your starred projects, including: - Project description, including name, description, and icon. @@ -284,8 +277,8 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: -1. On the top bar, select **Menu > Projects > Your Projects**. -1. Under **Your projects**, select **Personal**. +1. On the top bar, select **Main menu > Projects > View all projects**. +1. In the **Your projects** tab, select **Personal**. ## Delete a project @@ -294,9 +287,7 @@ you can [enable delayed project removal](../group/manage.md#enable-delayed-proje To delete a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. @@ -315,7 +306,7 @@ 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 **Menu > Projects > Explore projects**. +1. On the top bar, select **Main menu > Projects > View all 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. @@ -330,9 +321,7 @@ Each project in the list shows: To view the activity of a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select 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. Select a tab to view the type of project activity. @@ -340,7 +329,7 @@ To view the activity of a project: You can search through your projects. -1. On the top bar, select **Menu**. +1. On the top bar, select **Main menu**. 1. In **Search your projects**, type the project name. GitLab filters as you type. @@ -366,9 +355,7 @@ member and cannot contribute. To leave a project: -1. On the top bar, select **Menu > Projects**. -1. Select **Your projects** or **Explore projects**. -1. Select a project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Leave project**. The **Leave project** option only displays on the project dashboard when a project is part of a group under a [group namespace](../namespace/index.md). |
