diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 18:44:42 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 18:44:42 +0300 |
| commit | 4555e1b21c365ed8303ffb7a3325d773c9b8bf31 (patch) | |
| tree | 5423a1c7516cffe36384133ade12572cf709398d /doc/user/project | |
| parent | e570267f2f6b326480d284e0164a6464ba4081bc (diff) | |
Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42
Diffstat (limited to 'doc/user/project')
159 files changed, 2273 insertions, 1843 deletions
diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index 76ae4cf596b..d9e268251b7 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,67 +1,8 @@ --- -stage: Plan -group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'issues/managing_issues.md' --- -# Bulk editing issues and merge requests at the project level +This document was moved to [another location](issues/managing_issues.md). -NOTE: -Bulk editing issues, epics, and merge requests is also available at the **group level**. -For more details, see -[Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). - -If you want to update attributes across multiple issues or merge requests, you can do it -by bulk editing them, that is, editing them together. - -Only the items visible on the current page are selected for bulk editing (up to 20). - - - -## Bulk edit issues at the project level - -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. -> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. -> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. - -Users with permission level of [Reporter or higher](../permissions.md) can manage issues. - -When bulk editing issues in a project, you can edit the following attributes: - -- Status (open/closed) -- Assignee -- [Epic](../group/epics/index.md) -- [Milestone](milestones/index.md) -- [Labels](labels.md) -- [Health status](issues/managing_issues.md#health-status) -- Notification subscription -- [Iteration](../group/iterations/index.md) - -To update multiple project issues at the same time: - -1. In a project, go to **{issues}** **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit merge requests at the project level - -Users with permission level of [Developer or higher](../permissions.md) can manage merge requests. - -When bulk editing merge requests in a project, you can edit the following attributes: - -- Status (open/closed) -- Assignee -- Milestone -- Labels -- Subscriptions - -To update multiple project merge requests at the same time: - -1. In a project, go to **{merge-request}** **Merge Requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with - editable fields. -1. Select the checkboxes next to each merge request you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. +<!-- This redirect file can be deleted after <2021-08-12>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index e329ec4f903..c0fb8f5848f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -41,9 +41,9 @@ For example, the following policy document allows assuming a role whose name sta } ``` -### Administration settings +### Configure Amazon authentication -Generate an access key for the IAM user, and configure GitLab with the credentials: +To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and following the steps below. 1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. @@ -232,7 +232,7 @@ sequenceDiagram First, GitLab must obtain an initial set of credentials to communicate with the AWS API. These credentials can be retrieved in one of two ways: -- Statically through the [Administration settings](#administration-settings). +- Statically through the [Configure Amazon authentication](#configure-amazon-authentication). - Dynamically via an IAM instance profile ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7). After GitLab retrieves the AWS credentials, it makes an @@ -272,7 +272,7 @@ arn:aws:iam::123456789012:role/gitlab-eks-provision' #### Access denied: User `arn:aws:iam::x` is not authorized to perform: `sts:AssumeRole` on resource: `arn:aws:iam::y` This error occurs when the credentials defined in the -[Administration settings](#administration-settings) cannot assume the role defined by the +[Configure Amazon authentication](#configure-amazon-authentication) cannot assume the role defined by the Provision Role ARN. Check that: 1. The initial set of AWS credentials [has the AssumeRole policy](#additional-requirements-for-self-managed-instances). @@ -290,6 +290,10 @@ because GitLab has successfully assumed your provided role, but the role has insufficient permissions to retrieve the resources needed for the form. Make sure you've assigned the role the correct permissions. +### Key Pairs are not loaded + +GitLab loads the key pairs from the **Cluster Region** specified. Ensure that key pair exists in that region. + #### `ROLLBACK_FAILED` during cluster creation The creation process halted because GitLab encountered an error when creating diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index d64ebfd9385..fa4a5fb61d0 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -77,5 +77,5 @@ necessary components with GMAv2 and the cluster management project. **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) - [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 14db98c7ce7..bf419c69885 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -52,7 +52,7 @@ Each method has benefits and drawbacks: | | YAML method | UI method (Ultimate only) | |--|:------------|:-------------------------------| -| **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | +| **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/approvals/index.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | | **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. | Users are encouraged to choose one of the two methods to manage their policies. If users attempt to @@ -149,5 +149,5 @@ necessary components with GMAv2 and the cluster management project. **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) - [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md deleted file mode 100644 index d734db6bac9..00000000000 --- a/doc/user/project/clusters/securing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'protect/index.md' ---- - -This document was moved to [another location](protect/index.md). - -<!-- This redirect file can be deleted after <2021-04-01>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index f9423c0be2d..5d6fb8252bb 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -86,7 +86,7 @@ Put the following code in the file: service: gitlab-example provider: name: aws - runtime: nodejs10.x + runtime: nodejs14.x functions: hello: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 3135aa78719..ea7bcce99c1 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -22,19 +22,19 @@ The GitLab Code Owners feature defines who owns specific files or paths in a repository, allowing other users to understand who is responsible for each file or path. +As an alternative to using Code Owners for approvals, you can instead +[configure rules](merge_requests/approvals/rules.md). + ## Why is this useful? Code Owners allows for a version controlled, single source of truth file outlining the exact GitLab users or groups that -own certain files or paths in a repository. Code Owners can be -used in the merge request approval process which can streamline -the process of finding the right reviewers and approvers for a given -merge request. - -In larger organizations or popular open source projects, Code Owners -can help you understand who to contact if you have -a question that may not be related to code review or a merge request -approval. +own certain files or paths in a repository. In larger organizations +or popular open source projects, Code Owners can help you understand +who to contact if you have a question about a specific portion of +the codebase. Code Owners can also streamline the merge request approval +process, identifying the most relevant reviewers and approvers for a +given change. ## How to set up Code Owners @@ -76,7 +76,7 @@ The user that would show for `README.md` would be `@user2`. After you've added Code Owners to a project, you can configure it to be used for merge request approvals: -- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). +- As [merge request eligible approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** Developer or higher [permissions](../permissions.md) are required to @@ -87,9 +87,9 @@ After it's set, Code Owners are displayed in merge request widgets:  While you can use the `CODEOWNERS` file in addition to Merge Request -[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), +[Approval Rules](merge_requests/approvals/rules.md), you can also use it as the sole driver of merge request approvals -without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules): +without using [Approval Rules](merge_requests/approvals/rules.md): 1. Create the file in one of the three locations specified above. 1. Set the code owners as required approvers for @@ -143,6 +143,10 @@ But you have the option to [invite](members/share_project_with_groups.md) the Subgroup Y to the Project A so that their members also become eligible Code Owners: +NOTE: +If you do not invite Subgroup Y to Project A, but make them Code Owners, their approval +of the merge request becomes optional. +  After being invited, any member (`@user`) of the group or subgroup can be set diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 368417ac00b..804c013d317 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -8,7 +8,13 @@ type: howto, reference # Deploy Boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Free in 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. +> - In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as +> duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) +> in GitLab 13.6. +> - In GitLab 13.11 and earlier, environments in folders do not show deploy boards. +> This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in +> GitLab 13.12. GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -46,10 +52,6 @@ knowledge. In particular, you should be familiar with: - [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as -duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) -in GitLab 13.6. - ## Use cases Since the Deploy Board is a visual representation of the Kubernetes pods for a diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index a45c3d26f1a..a6b54474a9e 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -151,6 +151,24 @@ Adding a public deploy key does not immediately expose any repository to it. Pub deploy keys enable access from other systems, but access is not given to any project until a project maintainer chooses to make use of it. +## How to disable deploy keys + +[Project maintainers and owners](../../permissions.md#project-members-permissions) +can remove or disable a deploy key for a project repository: + +1. Navigate to the project's **Settings > Repository** page. +1. Expand the **Deploy keys** section. +1. Select the **{remove}** or **{cancel}** button. + +NOTE: +If anything relies on the removed deploy key, it will stop working once removed. + +If the key is **publicly accessible**, it will be removed from the project, but still available under **Publicly accessible deploy keys**. + +If the key is **privately accessible** and only in use by this project, it will deleted. + +If the key is **privately accessible** and in use by other projects, it will be removed from the project, but still available under **Privately accessible deploy keys**. + ## Troubleshooting ### Deploy key cannot push to a protected branch @@ -158,7 +176,7 @@ until a project maintainer chooses to make use of it. If the owner of this deploy key doesn't have access to a [protected branch](../protected_branches.md), then this deploy key doesn't have access to the branch either. In addition to this, choosing the **No one** value in -[the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) +[the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) means that no users **and** no services using deploy keys can push to that selected branch. Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 842f167f6ec..e2fa63ce519 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -130,20 +130,12 @@ To pull packages in the GitLab package registry, you must: 1. For the [package type of your choice](../../packages/index.md), follow the authentication instructions for deploy tokens. -Example request publishing a generic package using a deploy token: +Example request publishing a NuGet package using a deploy token: ```shell -curl --header "DEPLOY-TOKEN: <deploy_token>" \ - --upload-file path/to/file.txt \ - "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" -``` - -Example response: +nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdf -```json -{ - "message":"201 Created" -} +nuget push mypkg.nupkg -Source GitLab ``` ### Push or upload packages diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index b51a1b79a13..576de63d00d 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -15,7 +15,7 @@ Although branching strategies usually work well enough for source code and plain text because different versions can be merged together, they do not work for binary files. -When file locking is setup, lockable files are **read only** by default. +When file locking is setup, lockable files are **read-only** by default. When a file is locked, only the user who locked the file may modify it. This user is said to "hold the lock" or have "taken the lock", since only one user diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index c914c90c923..2e5713e10be 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -49,3 +49,21 @@ file is in your default branch (usually `master`). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). + +## Configure maximum file size for highlighting + +You can configure the maximum size of the file to be highlighted. + +The file size is measured in kilobytes, and is set to a default of `512 KB`. Any file _over_ the file size is rendered in plain text. + +1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) configuration file. + +1. Add this section, replacing `maximum_text_highlight_size_kilobytes` with the value you want. + + ```yaml + gitlab: + extra: + ## Maximum file size for syntax highlighting + ## https://docs.gitlab.com/ee/user/project/highlighting.html + maximum_text_highlight_size_kilobytes: 512 + ``` diff --git a/doc/user/project/img/bulk-editing_v13_2.png b/doc/user/project/img/bulk-editing_v13_2.png Binary files differdeleted file mode 100644 index 871cb02c01f..00000000000 --- a/doc/user/project/img/bulk-editing_v13_2.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_list_v12_3.png b/doc/user/project/img/protected_branches_list_v12_3.png Binary files differdeleted file mode 100644 index 995a294b85c..00000000000 --- a/doc/user/project/img/protected_branches_list_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_page_v12_3.png b/doc/user/project/img/protected_branches_page_v12_3.png Binary files differdeleted file mode 100644 index 60aa3c4d251..00000000000 --- a/doc/user/project/img/protected_branches_page_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/time_tracking_report_v13_12.png b/doc/user/project/img/time_tracking_report_v13_12.png Binary files differnew file mode 100644 index 00000000000..2132ca01cf4 --- /dev/null +++ b/doc/user/project/img/time_tracking_report_v13_12.png diff --git a/doc/user/project/img/time_tracking_sidebar_v13_12.png b/doc/user/project/img/time_tracking_sidebar_v13_12.png Binary files differnew file mode 100644 index 00000000000..e25282bc551 --- /dev/null +++ b/doc/user/project/img/time_tracking_sidebar_v13_12.png diff --git a/doc/user/project/img/time_tracking_sidebar_v8_16.png b/doc/user/project/img/time_tracking_sidebar_v8_16.png Binary files differdeleted file mode 100644 index 22124afed6f..00000000000 --- a/doc/user/project/img/time_tracking_sidebar_v8_16.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 6f274dd12a2..e77932c6427 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -14,26 +14,27 @@ Server (aka Stash). If you are trying to import projects from Bitbucket Server, Import your projects from Bitbucket Cloud to GitLab with minimal effort. -## Overview - -- At its current state, the Bitbucket importer can import: - - the repository description (GitLab 7.7+) - - the Git repository data (GitLab 7.7+) - - the issues (GitLab 7.7+) - - the issue comments (GitLab 8.15+) - - the pull requests (GitLab 8.4+) - - the pull request comments (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the wiki (GitLab 8.15+) -- References to pull requests and issues are preserved (GitLab 8.7+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. +The Bitbucket importer can import: + +- Repository description (GitLab 7.7+) +- Git repository data (GitLab 7.7+) +- Issues (GitLab 7.7+) +- Issue comments (GitLab 8.15+) +- Pull requests (GitLab 8.4+) +- Pull request comments (GitLab 8.15+) +- Milestones (GitLab 8.15+) +- Wiki (GitLab 8.15+) + +When importing: + +- References to pull requests and issues are preserved (GitLab 8.7+). +- Repository public access is retained. If a repository is private in Bitbucket, it's created as + private in GitLab as well. ## Requirements -The [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be first enabled in order to be -able to import your projects from Bitbucket Cloud. Ask your GitLab administrator -to enable this if not already. +To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) +must be enabled. Ask your GitLab administrator to enable this if it isn't already enabled. ## How it works diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index bb2256c9464..1e79107d76f 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -15,51 +15,49 @@ Use the [Bitbucket Cloud importer](bitbucket.md) for that. Import your projects from Bitbucket Server to GitLab with minimal effort. -## Overview +The Bitbucket importer can import: -- In its current state, the Bitbucket importer can import: - - the repository description (GitLab 11.2+) - - the Git repository data (GitLab 11.2+) - - the pull requests (GitLab 11.2+) - - the pull request comments (GitLab 11.2+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. +- Repository description (GitLab 11.2+) +- Git repository data (GitLab 11.2+) +- Pull requests (GitLab 11.2+) +- Pull request comments (GitLab 11.2+) + +When importing, repository public access is retained. If a repository is private in Bitbucket, it's +created as private in GitLab as well. ## Limitations -1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any - Bitbucket comments out of bounds will be inserted as comments in the merge - request. -1. Bitbucket Server allows multiple levels of threading. GitLab import - will collapse this into one thread and quote part of the original comment. -1. Declined pull requests have unreachable commits, which prevents the GitLab - importer from generating a proper diff. These pull requests will show up as - empty changes. -1. Attachments in Markdown are currently not imported. -1. Task lists are not imported. -1. Emoji reactions are not imported -1. Project filtering does not support fuzzy search (only `starts with` or `full - match strings` are currently supported) +- GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds + are inserted as comments in the merge request. +- Bitbucket Server allows multiple levels of threading. GitLab import collapses this into one thread + and quote part of the original comment. +- Declined pull requests have unreachable commits, which prevents the GitLab importer from + generating a proper diff. These pull requests show up as empty changes. +- Attachments in Markdown are not imported. +- Task lists are not imported. +- Emoji reactions are not imported. +- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are + supported). ## How it works The Bitbucket Server importer works as follows: -1. The user will be prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. +1. The user is prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. These credentials are preserved only as long as the importer is running. -1. The importer will attempt to list all the current repositories on the Bitbucket Server. -1. Upon selection, the importer will clone the repository and import pull requests and comments. +1. The importer attempts to list all the current repositories on the Bitbucket Server. +1. Upon selection, the importer clones the repository and import pull requests and comments. ### User assignment When issues/pull requests are being imported, the Bitbucket importer tries to find the author's e-mail address with a confirmed e-mail address in the GitLab user database. If no such user is available, the project creator is set as -the author. The importer will append a note in the comment to mark the original +the author. The importer appends a note in the comment to mark the original creator. -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. #### User assignment by username @@ -104,7 +102,7 @@ To disable it: Feature.disable(:bitbucket_server_user_mapping_by_username) ``` -## Importing your Bitbucket repositories +## Import your Bitbucket repositories 1. Sign in to GitLab and go to your dashboard. 1. Click on **New project**. @@ -118,7 +116,7 @@ Feature.disable(:bitbucket_server_user_mapping_by_username)  1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which each project will be + You can also filter projects by name and select the namespace under which each project is imported.  diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 1371ca57bc9..09505d94a8c 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -8,12 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab It only takes a few simple steps to import your project from FogBugz. -The importer will import all of your cases and comments with original case -numbers and timestamps. You will also have the opportunity to map FogBugz -users to GitLab users. +The importer imports all your cases and comments with original case +numbers and timestamps. You can also map FogBugz users to GitLab users. -1. From your GitLab dashboard click 'New project' -1. Click on the 'FogBugz' button +Follow these steps to import your project from FogBugz: + +1. From your GitLab dashboard, select **New project**. + +1. Select the **FogBugz** button.  @@ -25,11 +27,11 @@ users to GitLab users.  -1. Select the projects you wish to import by clicking the Import buttons +1. Select the projects you wish to import by selecting the **Import** buttons.  -1. Once the import has finished click the link to take you to the project +1. Once the import finishes, click the link to go to the project dashboard. Follow the directions to push your existing repository.  diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index bac10cb0948..5a4b16d57f5 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,117 +1,8 @@ --- -type: reference, howto -stage: Manage -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 +redirect_to: 'index.md' --- -# Gemnasium **(ULTIMATE)** +This document was deleted. -This guide describes how to migrate from Gemnasium.com to your own GitLab -instance or GitLab.com. - -## Why is Gemnasium.com closed? - -Gemnasium was [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html) -in January 2018. Since May 15, 2018, the services provided by Gemnasium are no longer available. -The team behind Gemnasium has joined GitLab as the new Security Products team -and is working on a [wide range of tools](../../application_security/index.md), -including: - -- [Dependency Scanning](../../application_security/dependency_scanning/index.md) -- [SAST](../../application_security/sast/index.md) -- [DAST](../../application_security/dast/index.md) -- [Container Scanning](../../application_security/container_scanning/index.md) - -If you want to continue monitoring your dependencies, see the -[Migrating to GitLab](#migrating-to-gitlab) section below. - -## What happened to my account? - -Your account has been automatically closed on May 15th, 2018. If you had a paid -subscription at that time, your card will be refunded on a -<!-- vale gitlab.Spelling = NO --> pro rata temporis <!-- vale gitlab.Spelling = YES --> basis. -You may contact `gemnasium@gitlab.com` regarding your closed account. - -## Will my account/data be transferred to GitLab Inc.? - -All accounts and data have been deleted on May 15th, 2018. GitLab Inc. -doesn't know anything about your private data, nor your projects, and therefore -if they were vulnerable or not. GitLab Inc. takes personal information very seriously. - -## What happened to my badge? - -To avoid broken 404 images, all badges pointing to Gemnasium.com will be a -placeholder, inviting you to migrate to GitLab (and pointing to this page). - -## Migrating to GitLab - -Gemnasium has been ported and integrated directly into GitLab CI/CD. -You can still benefit from our dependency monitoring features, and it requires -some steps to migrate your projects. There is no automatic import since GitLab -doesn't know anything about any projects which existed on Gemnasium.com. -Security features are free for public (open-source) projects hosted on GitLab.com. - -### If your project is hosted on GitLab (`https://gitlab.com` / self-managed) - -You're almost set! If you're already using -[Auto DevOps](../../../topics/autodevops/), you are already covered. -Otherwise, you must configure your `.gitlab-ci.yml` according to the -[dependency scanning page](../../application_security/dependency_scanning/index.md). - -### If your project is hosted on GitHub (`https://github.com` / GitHub Enterprise) - -Since [GitLab 10.6 comes with GitHub integration](https://about.gitlab.com/solutions/github/), -GitLab users can now create a CI/CD project in GitLab connected to an external -GitHub.com or GitHub Enterprise repository. This will automatically prompt -GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results -back to both GitLab and GitHub when completed. - -<!-- vale gitlab.Spelling = NO --> - -1. Create a new project, and select **CI/CD for external repo**: - -  - <!-- vale gitlab.Spelling = YES --> - -1. Use the **GitHub** button to connect your repositories. - -  - -1. Select the project(s) to be set up with GitLab CI/CD and choose **Connect**. - -  - - After the configuration is done, you may click on your new - project on GitLab. - -  - - Your project is now mirrored on GitLab, where the runners will be able to access - your source code and run your tests. - - Optional step: If you set this up on GitLab.com, make sure the project is - public (in the project settings) if your GitHub project is public, since - the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing/). - -1. To set up the dependency scanning job, corresponding to what Gemnasium was - doing, you must create a `.gitlab-ci.yml` file, or update it according to - the [dependency scanning docs](../../application_security/dependency_scanning/index.md). - The mirroring is pull-only by default, so you may create or update the file on - GitHub: - -  - -1. Once your file has been committed, a new pipeline will be automatically - triggered if your file is valid: - -  - -1. The result of the job will be visible directly from the pipeline view: - -  - -NOTE: -If you don't commit very often to your project, you may want to use -[scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular -basis. +<!-- This redirect file can be deleted after <2021-08-15>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 26e5a86b808..41141902468 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -9,20 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import your projects from Gitea to GitLab with minimal effort. -## Overview - NOTE: This requires Gitea `v1.0.0` or newer. -- At its current state, Gitea importer can import: - - the repository description (GitLab 8.15+) - - the Git repository data (GitLab 8.15+) - - the issues (GitLab 8.15+) - - the pull requests (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the labels (GitLab 8.15+) -- Repository public access is retained. If a repository is private in Gitea - it will be created as private in GitLab as well. +The Gitea importer can import: + +- Repository description (GitLab 8.15+) +- Git repository data (GitLab 8.15+) +- Issues (GitLab 8.15+) +- Pull requests (GitLab 8.15+) +- Milestones (GitLab 8.15+) +- Labels (GitLab 8.15+) + +When importing, repository public access is retained. If a repository is private in Gitea, it's +created as private in GitLab as well. ## How it works @@ -31,23 +31,23 @@ to users in your GitLab instance. This means that the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Gitea author is kept. -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. -## Importing your Gitea repositories +## Import your Gitea repositories The importer page is visible when you create a new project.  -Click on the **Gitea** link and the import authorization process will start. +Click the **Gitea** link and the import authorization process starts.  ### Authorize access to your repositories using a personal access token -With this method, you will perform a one-off authorization with Gitea to grant +With this method, you perform a one-off authorization with Gitea to grant GitLab access your repositories: 1. Go to `https://your-gitea-instance/user/settings/applications` (replace @@ -58,27 +58,27 @@ GitLab access your repositories: 1. Copy the token hash. 1. Go back to GitLab and provide the token to the Gitea importer. 1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads - your repositories' information. Once done, you'll be taken to the importer + your repositories' information. Once done, you are taken to the importer page to select the repositories to import. ### Select which repositories to import -After you've authorized access to your Gitea repositories, you will be +After you've authorized access to your Gitea repositories, you are redirected to the Gitea importer page. From there, you can see the import statuses of your Gitea repositories. -- Those that are being imported will show a _started_ status, -- those already successfully imported will be green with a _done_ status, -- whereas those that are not yet imported will have an **Import** button on the +- Those that are being imported show a _started_ status, +- those already successfully imported are green with a _done_ status, +- whereas those that are not yet imported have an **Import** button on the right side of the table. You also can: - Import all your Gitea projects in one go by hitting **Import all projects** in - the upper left corner + the upper left corner. - Filter projects by name. If filter is applied, hitting **Import all projects** - will only import matched projects + only imports matched projects.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eb426a9f126..c8b973b673e 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -10,8 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Using the importer, you can import your GitHub repositories to GitLab.com or to your self-managed GitLab instance. -## Overview - The following aspects of a project are imported: - Repository description (GitLab.com & 7.7+) @@ -37,12 +35,12 @@ The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `git This process does not migrate or import any types of groups or organizations from GitHub to GitLab. -### Use cases +## Use cases The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. - If you're importing to GitLab.com, you can alternatively import GitHub repositories - using a [personal access token](#using-a-github-token). We do not recommend + 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. - If you're importing to a self-managed GitLab instance, you can alternatively use the @@ -62,9 +60,16 @@ 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 publicly visible - [primary email address](https://docs.github.com/en/rest/reference/users#get-a-user) - on their profile that matches their GitLab account's primary or secondary email address. +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) + that matches their GitLab account's email address. + + NOTE: + GitLab content imports that use GitHub accounts require that the GitHub public-facing + email address is populated so that all comments and contributions are properly mapped + to the same user in GitLab. GitHub Enterprise (on premise) does not require this field + to be populated to use the product, so you may need to add it on existing GitHub Enterprise + accounts for imported content to be properly mapped to the user in the new system. + Refer to GitHub documentation for instructions on how to add that address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original @@ -86,7 +91,7 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Import your GitHub repository into GitLab -### Using the GitHub integration +### Use the GitHub integration Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: @@ -105,9 +110,9 @@ If you are using a self-managed GitLab instance or if you are importing from Git 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. 1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. -1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). +1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import). -### Using a GitHub token +### Use a GitHub token NOTE: Using a personal access token to import projects is not recommended. If you are a GitLab.com user, @@ -115,7 +120,7 @@ you can use a personal access token to import your project from GitHub, but this associate all user activity (such as issues and pull requests) with matching GitLab users. If you are an administrator of a self-managed GitLab instance or if you are importing from GitHub Enterprise, you cannot use a personal access token. -The [GitHub integration method (above)](#using-the-github-integration) is recommended for all users. +The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users. Read more in the [How it works](#how-it-works) section. If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: @@ -129,7 +134,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. Once done, you'll be taken to the importer page to select the repositories to import. -### Selecting which repositories to import +### Select which repositories to import After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and your GitHub repositories are listed. @@ -155,7 +160,7 @@ Additionally, you can configure GitLab to send pipeline status updates back GitH If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both of the above are automatically configured. **(PREMIUM)** -## Improving the speed of imports on self-managed instances +## Improve the speed of imports on self-managed instances NOTE: Administrator access to the GitLab server is required. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index add457c217e..9e63b1cb617 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -19,10 +19,10 @@ you'll need to follow the instructions for [exporting a project](../settings/imp  -Go to the **Import Projects** tab, then click on **GitLab.com**, and you will be redirected to GitLab.com -for permission to access your projects. After accepting, you'll be automatically redirected to the importer. +Go to the **Import Projects** tab, then click on **GitLab.com**, and you are redirected to GitLab.com +for permission to access your projects. After accepting, you are automatically redirected to the importer.  -To import a project, click "Import". The importer will import your repository and issues. -Once the importer is done, a new GitLab project will be created with your imported data. +To import a project, click "Import". The importer imports your repository and issues. +Once the importer is done, a new GitLab project is created with your imported data. diff --git a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png Binary files differdeleted file mode 100644 index 575d257a213..00000000000 --- a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/create_project_v13_5.png b/doc/user/project/import/img/gemnasium/create_project_v13_5.png Binary files differdeleted file mode 100644 index 37467bc3fed..00000000000 --- a/doc/user/project/import/img/gemnasium/create_project_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png Binary files differdeleted file mode 100644 index 8336c803b83..00000000000 --- a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/pipeline.png b/doc/user/project/import/img/gemnasium/pipeline.png Binary files differdeleted file mode 100644 index ae4d5295ffa..00000000000 --- a/doc/user/project/import/img/gemnasium/pipeline.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differdeleted file mode 100644 index 332d2230ef8..00000000000 --- a/doc/user/project/import/img/gemnasium/project_connected.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/select_project_v13_5.png b/doc/user/project/import/img/gemnasium/select_project_v13_5.png Binary files differdeleted file mode 100644 index 30575954811..00000000000 --- a/doc/user/project/import/img/gemnasium/select_project_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png Binary files differindex 8a94d33d47b..dca60b2bc5c 100644 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png +++ b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index f6ed53763dd..3728a486070 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -5,50 +5,52 @@ 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 projects to a GitLab instance - -1. [From Bitbucket Cloud](bitbucket.md) -1. [From Bitbucket Server (also known as Stash)](bitbucket_server.md) -1. [From ClearCase](clearcase.md) -1. [From CVS](cvs.md) -1. [From FogBugz](fogbugz.md) -1. [From GitHub.com or GitHub Enterprise](github.md) -1. [From GitLab.com](gitlab_com.md) -1. [From Gitea](gitea.md) -1. [From Perforce](perforce.md) -1. [From SVN](svn.md) -1. [From TFVC](tfvc.md) -1. [From repository by URL](repo_by_url.md) -1. [By uploading a manifest file (AOSP)](manifest.md) -1. [From Gemnasium](gemnasium.md) -1. [From Phabricator](phabricator.md) -1. [From Jira (issues only)](jira.md) - -In addition to the specific migration documentation above, you can import any -Git repository via HTTP from the New Project page. Be aware that if the -repository is too large the import can timeout. - -There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +# Migrate projects to a GitLab instance + +See these documents to migrate to GitLab: + +- [From Bitbucket Cloud](bitbucket.md) +- [From Bitbucket Server (also known as Stash)](bitbucket_server.md) +- [From ClearCase](clearcase.md) +- [From CVS](cvs.md) +- [From FogBugz](fogbugz.md) +- [From GitHub.com or GitHub Enterprise](github.md) +- [From GitLab.com](gitlab_com.md) +- [From Gitea](gitea.md) +- [From Perforce](perforce.md) +- [From SVN](svn.md) +- [From TFVC](tfvc.md) +- [From repository by URL](repo_by_url.md) +- [By uploading a manifest file (AOSP)](manifest.md) +- [From Phabricator](phabricator.md) +- [From Jira (issues only)](jira.md) + +You can also import any Git repository through HTTP from the **New Project** page. Note that if the +repository is too large, the import can timeout. + +You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** ## LFS authentication When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. -## Migrating from self-managed GitLab to GitLab.com +## Migrate from self-managed GitLab to GitLab.com -If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. - -If you want to retain all metadata like issues and merge requests, you can use -the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. - -All GitLab user associations (such as comment author) will be changed to the user importing the project. For more information, please see [the import notes](../settings/import_export.md#important-notes). - -If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com. -The order of assets to migrate from a self-managed instance to GitLab.com is the following: +If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). +However, you can't import issues and merge requests this way. To retain all metadata like issues and +merge requests, use the [import/export feature](../settings/import_export.md) +to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab +user associations (such as comment author) are changed to the user importing the project. For more +information, see [the import notes](../settings/import_export.md#important-notes). NOTE: -When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access. +When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) +will be used. Creating users with the API is limited to self-managed instances as it requires +administrator access. + +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/README.md). +Migrate the assets in this order: 1. [Groups](../../../api/groups.md) 1. [Projects](../../../api/projects.md) @@ -56,43 +58,43 @@ When migrating to GitLab.com, users would need to be manually created unless [SC Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents). -You will still need to migrate your Container Registry over a series of -Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts. +You must still migrate your [Container Registry](../../packages/container_registry/) +over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. -## Migrating from GitLab.com to self-managed GitLab +## Migrate from GitLab.com to self-managed GitLab -The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation). +The process is essentially the same as [migrating from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). +The main difference is that an administrator can create users on the self-managed GitLab instance +through the UI or the [users API](../../../api/users.md#user-creation). -## Migrating between two self-managed GitLab instances +## Migrate between two self-managed GitLab instances -The best method for migrating from one GitLab instance to another, -perhaps from an old server to a new server for example, is to -[back up the instance](../../../raketasks/backup_restore.md), -then restore it on the new server. +To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's +best to [back up](../../../raketasks/backup_restore.md) +the existing instance and restore it on the new instance. For example, this is useful when migrating +a self-managed instance from an old server to a new server. -In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), -refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). +To instead merge two self-managed GitLab instances together, use the instructions in +[Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). +This method is useful when both self-managed instances have existing data that must be preserved. -Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. +Also note that administrators can use the [Users API](../../../api/users.md) +to migrate users. ## Project aliases **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. -When migrating repositories to GitLab and they are being accessed by other systems, -it's very useful to be able to access them using the same name especially when -they are a lot. It reduces the risk of changing significant number of Git URLs in -a large number of systems. - -GitLab provides a functionality to help with this. In GitLab, repositories are -usually accessed with a namespace and project name. It is also possible to access -them via a project alias. This feature is only available on Git over SSH. +GitLab repositories are usually accessed with a namespace and a project name. When migrating +frequently accessed repositories to GitLab, however, you can use project aliases to access those +repositories with the original name. Accessing repositories through a project alias reduces the risk +associated with migrating such repositories. -A project alias can be only created via API and only by GitLab administrators. -Follow the [Project Aliases API documentation](../../../api/project_aliases.md) for -more details. +This feature is only available on Git over SSH. Also, only GitLab administrators can create project +aliases, and they can only do so through the API. For more information, see the +[Project Aliases API documentation](../../../api/project_aliases.md). -After an alias has been created for a project (such as an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository -with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of -`git clone git@gitlab.com:gitlab-org/gitlab.git`). +After an administrator creates an alias for a project, you can use the alias to clone the +repository. For example, if an administrator creates the alias `gitlab` for the project +`https://gitlab.com/gitlab-org/gitlab`, you can clone the project with +`git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 5fb737cf74a..4273f90c1e7 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -54,13 +54,13 @@ Make sure you have the integration set up before trying to import Jira issues. > New import form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216145) in GitLab 13.2. -To import Jira issues to a GitLab project, follow the steps below. - NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. Importing large projects may take several minutes depending on the size of the import. +To import Jira issues to a GitLab project: + 1. On the **{issues}** **Issues** page, click **Import Issues** (**{import}**) **> Import from Jira**.  diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 6ef91a54987..94eba319a17 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -29,7 +29,7 @@ A manifest must be an XML file. There must be one `remote` tag with a `review` attribute that contains a URL to a Git server, and each `project` tag must have a `name` and `path` attribute. GitLab will then build the URL to the repository by combining the URL from the `remote` tag with a project name. -A path attribute will be used to represent the project path in GitLab. +A path attribute is used to represent the project path in GitLab. Below is a valid example of a manifest file: @@ -42,23 +42,23 @@ Below is a valid example of a manifest file: </manifest> ``` -As a result, the following projects will be created: +As a result, the following projects are created: | GitLab | Import URL | |:------------------------------------------------|:------------------------------------------------------------| | `https://gitlab.com/YOUR_GROUP/build/make` | <https://android.googlesource.com/platform/build> | | `https://gitlab.com/YOUR_GROUP/build/blueprint` | <https://android.googlesource.com/platform/build/blueprint> | -## Importing the repositories +## Import the repositories -You can start the import with: +To start the import: -1. From your GitLab dashboard click **New project** -1. Switch to the **Import project** tab -1. Click on the **Manifest file** button -1. Provide GitLab with a manifest XML file -1. Select a group you want to import to (you need to create a group first if you don't have one) -1. Click **List available repositories**. At this point, you will be redirected +1. From your GitLab dashboard click **New project**. +1. Switch to the **Import project** tab. +1. Click on the **Manifest file** button. +1. Provide GitLab with a manifest XML file. +1. Select a group you want to import to (you need to create a group first if you don't have one). +1. Click **List available repositories**. At this point, you are redirected to the import status page with projects list based on the manifest file. 1. Check the list and click **Import all repositories** to start the import. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 91fd7b8928b..30a63a72cf9 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -20,7 +20,7 @@ GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. -Currently, only the following basic fields are imported: +Only the following basic fields are imported: - Title - Description @@ -34,6 +34,6 @@ The assignee and author of a user are deducted from a Task's owner and author: If a user with the same username has access to the namespace of the project being imported into, then the user will be linked. -## Enabling this feature +## Enable this feature Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index a816dca59bc..e39976e00f6 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -11,18 +11,16 @@ 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. -## Overview - There are two approaches to SVN to Git migration: -1. [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 to manage migration risks. +- [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. -1. [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. +- [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. ## Smooth migration with a Git/SVN mirror using SubGit @@ -38,15 +36,15 @@ directly in a file system level. 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 will be available at `/opt/subgit-VERSION/bin/subgit`. + command is available at `/opt/subgit-VERSION/bin/subgit`. ### SubGit configuration The first step to mirror you SVN repository in GitLab is to create a new empty -project which will be used as a mirror. For Omnibus installations the path to -the repository will be located at +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 will be +installations from source, the default repository directory is `/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a variable: @@ -54,7 +52,7 @@ variable: GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git ``` -SubGit will keep this repository in sync with a remote SVN project. For +SubGit keeps this repository in sync with a remote SVN project. For convenience, assign your remote SVN project URL to a variable: ```shell @@ -89,9 +87,9 @@ initial translation of existing SVN revisions into the Git repository: subgit install $GIT_REPO_PATH ``` -After the initial translation is completed, the Git repository and the SVN -project will be kept in sync by `subgit` - new Git commits will be translated to -SVN revisions and new SVN revisions will be translated to Git commits. Mirror +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. If you would prefer to perform one-time cut over migration with `subgit`, use @@ -134,12 +132,12 @@ 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 will not be attributed +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 will want to ensure they complete this step. If you choose to map authors -you will be required to map every author that is present on changes in the SVN -repository. If you don't, the conversion will fail and you will have to update -the author file accordingly. The following command will search through the +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 @@ -159,7 +157,7 @@ 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 will take some time. +running the `svn2git` command. The conversion process takes some time. ```shell svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt @@ -167,13 +165,13 @@ 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, etc. See +`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, where you will eventually push your converted code. +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 will push all commits, +repository as a Git remote and push all the changes. This pushes all commits, branches and tags. ```shell diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 0d347a16697..705df686fe0 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Migrating from TFVC to Git +# Migrate from TFVC to Git Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes @@ -46,12 +46,8 @@ Advantages of migrating to Git/GitLab: Migration options from TFVC to Git depend on your operating system. -- If you're migrating on Microsoft Windows: - - Use the [`git-tfs`](https://github.com/git-tfs/git-tfs) -tool. - Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) guide for details. - -- If you're on a Unix-based system: - - Follow the procedures described with this [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). +- If you're migrating on Microsoft Windows, use the [`git-tfs`](https://github.com/git-tfs/git-tfs) + tool. See [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) + for details. +- If you're on a Unix-based system, follow the procedures described with this + [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 7e5801a2382..d9283f623d4 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -45,7 +45,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. - [Merge Requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before + - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before implementing a change. - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results diff --git a/doc/user/project/insights/img/insights_sidebar_link_v12_8.png b/doc/user/project/insights/img/insights_sidebar_link_v12_8.png Binary files differdeleted file mode 100644 index b07ecc5286a..00000000000 --- a/doc/user/project/insights/img/insights_sidebar_link_v12_8.png +++ /dev/null diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 72897a1a26e..436df07d673 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -20,9 +20,7 @@ This feature is [also available at the group level](../../group/insights/index.m ## View your project's Insights You can access your project's Insights by clicking the **Analytics > Insights** -link in the left sidebar: - - +link in the left sidebar. ## Configure your Insights diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 7e14515d98e..e8427e36015 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,33 +4,55 @@ group: Ecosystem 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 --- -# Bugzilla Service **(FREE)** +# Bugzilla service **(FREE)** -Navigate to the [Integrations page](overview.md#accessing-integrations), -select the **Bugzilla** service and fill in the required details as described -in the table below. +[Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing +tool. -| Field | Description | -| ----- | ----------- | -| `project_url` | The URL to the project in Bugzilla which is being linked to this GitLab project. Note that the `project_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -| `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | -| `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | +You can configure Bugzilla as an +[external issue tracker](../../../integration/external-issue-tracker.md) in GitLab. -Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. +To enable the Bugzilla integration in a project: -## Referencing issues in Bugzilla +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Bugzilla**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: -Issues in Bugzilla can be referenced in two alternative ways: + - **Project URL**: The URL to the project in Bugzilla. + For example, for a product named "Fire Tanuki": + `https://bugzilla.example.org/describecomponents.cgi?product=Fire+Tanuki`. + - **Issue URL**: The URL to view an issue in the Bugzilla project. + The URL must contain `:id`. GitLab replaces `:id` with the issue number (for example, + `https://bugzilla.example.org/show_bug.cgi?id=:id`, which becomes + `https://bugzilla.example.org/show_bug.cgi?id=123`). + - **New issue URL**: The URL to create a new issue in the linked Bugzilla project. + For example, for a project named "My Cool App": + `https://bugzilla.example.org/enter_bug.cgi#h=dupes%7CMy+Cool+App`. -- `#<ID>` where `<ID>` is a number (example `#143`). -- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is - then followed by capital letters, numbers or underscores, and `<ID>` is - a number (example `API_32-143`). +1. Select **Save changes** or optionally select **Test settings**. -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. +After you configure and enable Bugzilla, a link appears on the GitLab +project pages. This link takes you to the appropriate Bugzilla project. -Please note that `<PROJECT>` part is ignored and links always point to the -address specified in `issues_url`. +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +Learn more about the steps and consequences of disabling GitLab issues in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). + +## Reference Bugzilla issues in GitLab + +You can reference issues in Bugzilla using: + +- `#<ID>`, where `<ID>` is a number (for example, `#143`). +- `<PROJECT>-<ID>` (for example `API_32-143`) where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. + +The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. ## Troubleshooting diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 9cc4e980212..19beafd6663 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,35 +4,43 @@ group: Ecosystem 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 --- -# Custom Issue Tracker service **(FREE)** +# Custom issue tracker service **(FREE)** -To enable the Custom Issue Tracker integration in a project: +Use a custom issue tracker that is not in the integration list. -1. Go to **Settings > Integrations**. -1. Click **Custom Issue Tracker** -1. Fill in the tracker's details, such as title, description, and URLs. - You can edit these fields later as well. +To enable a custom issue tracker in a project: - These are some of the required fields: +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Custom issue tracker**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: - | Field | Description | - | --------------- | ----------- | - | **Project URL** | The URL to the project in the custom issue tracker. | - | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Planned to be changed in a future release. | + - **Project URL**: The URL to view all the issues in the custom issue tracker. + - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`. + GitLab replaces `:id` with the issue number (for example, + `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`). + - **New issue URL**: + <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> + **This URL is not used and removal is planned in a future release.** + Enter any URL here. + For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -1. Click **Test settings and save changes**. +1. Select **Save changes** or optionally select **Test settings**. -After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab -project pages that takes you to that custom issue tracker. +After you configure and enable the custom issue tracker service, a link appears on the GitLab +project pages. This link takes you to the custom issue tracker. -## Referencing issues +## Reference issues in a custom issue tracker -Issues are referenced with `<ANYTHING>-<ID>` (for example, `PROJECT-143`), where `<ANYTHING>` can be any string in CAPS, and `<ID>` -is a number used in the target project of the custom integration. +You can reference issues in a custom issue tracker using: -`<ANYTHING>` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. +- `#<ID>`, where `<ID>` is a number (for example, `#143`). +- `<PROJECT>-<ID>` (for example `API_32-143`) where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. -When building the hyperlink, the `<ANYTHING>` part is ignored, and links always point to the address -specified in `issues_url`, so in the example above, `PROJECT-143` would refer to -`https://customissuetracker.com/project-name/143`. +The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d63599d02bc..5b0059673ad 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -6,31 +6,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w # IBM Engineering Workflow Management (EWM) Integration **(FREE)** -This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. +This service allows you to go from GitLab to EWM work items mentioned in merge request +descriptions and commit messages. +Each work item reference is automatically converted to a link to the work item. -NOTE: -This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. +This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is compatible with all versions of RTC and EWM. -1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. -1. Enter the information listed below. +To enable the EWM integration, in a project: - | Field | Description | - | ----- | ----------- | - | `project_url` | URL of the EWM project area to link to the GitLab project. To obtain your project area URL, navigate to the path `/ccm/web/projects` and copy the listed project's URL. For example, `https://example.com/ccm/web/Example%20Project` | - | `issues_url` | URL to the work item editor in the EWM project area. The format is `<your-server-url>/resource/itemName/com.ibm.team.workitem.WorkItem/:id`. For example, `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/:id` | - | `new_issue_url` | URL to create a new work item in the EWM project area. Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem` | +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **EWM**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: + + - **Project URL**: The URL to the EWM project area. + + To obtain your project area URL, navigate to the + path `/ccm/web/projects` and copy the listed project's URL. For example, `https://example.com/ccm/web/Example%20Project`. + - **Issue URL**: The URL to the work item editor in the EWM project area. + + The format is `<your-server-url>/resource/itemName/com.ibm.team.workitem.WorkItem/:id`. + GitLab replaces `:id` with the issue number + (for example, `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/:id`, + which becomes `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/123`). + - **New issue URL**: URL to create a new work item in the EWM project area. + + Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. + For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem`. + +1. Select **Save changes** or optionally select **Test settings**. ## Reference EWM work items in commit messages -You can use any of the keywords supported by the EWM Git Integration Toolkit to refer to work items. Work items can be referenced using the format: `<keyword> <id>`. +To refer to work items, you can use any keywords supported by the EWM Git Integration Toolkit. +Use the format: `<keyword> <id>`. You can use the following keywords: - `bug` -- `task` - `defect` - `rtcwi` -- `workitem` +- `task` - `work item` +- `workitem` -For more details, see the EWM documentation page [Creating links from commit comments](https://www.ibm.com/support/knowledgecenter/SSYMRC_7.0.0/com.ibm.team.connector.cq.doc/topics/t_creating_links_through_comments.html), which recommends against using the additionally-supported keyword `#` because of incompatibility with GitLab. +Avoid using the keyword `#`. Learn more in the EWM documentation page +[Creating links from commit comments](https://www.ibm.com/docs/en/elm/7.0.0?topic=commits-creating-links-from-commit-comments). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index d0efebd4da7..0668e5dd88f 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,32 +4,50 @@ group: Ecosystem 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 --- -# Hangouts Chat service **(FREE)** +# Google Chat integration **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. -The Hangouts Chat service sends notifications from GitLab to the room for which the webhook was created. +Integrate your project to send notifications from GitLab to a +room of your choice in [Google Chat](https://chat.google.com/) (former Google +Hangouts). -## On Hangouts Chat +## How it works -1. Open the chat room in which you want to see the notifications. -1. From the chat room menu, select **Configure Webhooks**. -1. Click on **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally define an avatar. -1. Click **SAVE** and copy the **Webhook URL** of your webhook. +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. -See also [the Hangouts Chat documentation for configuring incoming webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks) +After that, enable the integration in GitLab and choose the events you want to +be notified about in your Google Chat room. -## On GitLab +For every selected event in your project, GitLab acts like a bot sending +notifications to Google Chat: -When you have the **Webhook URL** for your Hangouts Chat room webhook, you can set up the GitLab service. + -1. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Hangouts Chat** integration to configure it. -1. Ensure that the **Active** toggle is enabled. -1. Check the checkboxes corresponding to the GitLab events you want to receive. -1. Paste the **Webhook URL** that you copied from the Hangouts Chat configuration step. -1. Configure the remaining options and click `Save changes`. +## In Google Chat -Your Hangouts Chat room now starts receiving GitLab event notifications as configured. +Select a room and create a webhook: - +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**. +1. Enter the name for your webhook, for example "GitLab integration". +1. (Optional) Add an avatar for your bot. +1. Select **Save**. +1. Copy the webhook URL. + +For further details, see [the Google Chat documentation for configuring webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks). + +## In GitLab + +Enable the Google Chat integration in GitLab: + +1. In your project, go to **Settings > Integrations** and select **Google Chat**. +1. Scroll down to the end of the page where you find a **Webhook** field. +1. Enter the webhook URL you copied from Google Chat. +1. Select the events you want to be notified about in your Google Chat room. +1. (Optional) Select **Test settings** to verify the connection. +1. Select **Save changes**. + +To test the integration, make a change based on the events you selected and +see the notification in your Google Chat room. diff --git a/doc/user/project/integrations/img/emails_on_push_service.png b/doc/user/project/integrations/img/emails_on_push_service.png Binary files differdeleted file mode 100644 index 43cef167369..00000000000 --- a/doc/user/project/integrations/img/emails_on_push_service.png +++ /dev/null diff --git a/doc/user/project/integrations/img/google_chat_integration_v13_11.png b/doc/user/project/integrations/img/google_chat_integration_v13_11.png Binary files differnew file mode 100644 index 00000000000..b2df55816d5 --- /dev/null +++ b/doc/user/project/integrations/img/google_chat_integration_v13_11.png diff --git a/doc/user/project/integrations/img/hangouts_chat_configuration.png b/doc/user/project/integrations/img/hangouts_chat_configuration.png Binary files differdeleted file mode 100644 index 1104f20ce2f..00000000000 --- a/doc/user/project/integrations/img/hangouts_chat_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 0a32119d572..18ff6e324e3 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -48,10 +48,16 @@ notification. You do not need to add the hash sign (`#`). Then fill in the integration configuration: -| Field | Description | -| ----- | ----------- | -| **Webhook** | The incoming webhook URL on Mattermost, similar to: `http://mattermost.example/hooks/5xo…`. | -| **Username** | (Optional) The username to show on messages sent to Mattermost. Fill this in to change the username of the bot. | -| **Notify only broken pipelines** | If you enable the **Pipeline** event and you want to be notified about failed pipelines only. | -| **Branches to be notified** | Select which branches to send notifications for. | -| **Labels to be notified** | (Optional) Labels that the issue or merge request must have to trigger a notification. Leave blank to get notifications for all issues and merge requests. | +- **Webhook**: The incoming webhook URL on Mattermost, similar to + `http://mattermost.example/hooks/5xo…`. +- **Username**: (Optional) The username shown in messages sent to Mattermost. + To change the bot's username, provide a value. +- **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want + notifications about failed pipelines only. +- **Branches to be notified**: The branches to send notifications for. +- **Labels to be notified**: (Optional) Labels required for the issue or merge request + to trigger a notification. Leave blank to notify for all issues and merge requests. +- **Labels to be notified behavior**: When you use the **Labels to be notified** filter, + messages are sent when an issue or merge request contains _any_ of the labels specified + in the filter. You can also choose to trigger messages only when the issue or merge request + contains _all_ the labels defined in the filter. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index ef1f492bfbf..5bd4062b125 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -39,9 +39,9 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | | [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | | [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | -| Flowdock | Use Flowdock with GitLab. | **{dotted-circle}** No | +| [Flowdock](../../../api/services.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | | [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | -| [Hangouts Chat](hangouts_chat.md) | Receive events notifications. | **{dotted-circle}** No | +| [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat.| **{dotted-circle}** No | | [Irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | | [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | | JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 0eaa9cae7c0..b35ebacbd31 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -31,7 +31,7 @@ Cloudwatch exporter retrieves and parses the specified Cloudwatch metrics, and translates them into a Prometheus monitoring endpoint. The only supported AWS resource is the Elastic Load Balancer, whose Cloudwatch -metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). +metrics are listed in [this AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). You can [download a sample Cloudwatch Exporter configuration file](../samples/cloudwatch.yml) that's configured for basic AWS ELB monitoring. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 6820412808f..b2bf8e5731a 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -6,25 +6,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Webex Teams service **(FREE)** -You can configure GitLab to send notifications to a Webex Teams space. +You can configure GitLab to send notifications to a Webex Teams space: + +1. Create a webhook for the space. +1. Add the webhook to GitLab. ## Create a webhook for the space 1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/messaging/applications/incoming-webhooks-cisco-systems-38054). -1. Click **Connect** and log in to Webex Teams, if required. +1. Select **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space to receive the notifications. -1. Click **ADD**. +1. Select **ADD**. 1. Copy the **Webhook URL**. ## Configure settings in GitLab -Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send notifications. +Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send +notifications: -1. Navigate to **Project > Settings > Integrations**. +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. + - **Settings > Integrations** in the Admin Area (**{admin}**) to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. 1. Paste the **Webhook** URL for the Webex Teams space. 1. Configure the remaining options and then click **Test settings and save changes**. -The Webex Teams space now begins to receive all applicable GitLab events. +The Webex Teams space begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 56a339e02d2..d74a2bec1f6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1368,6 +1368,7 @@ X-Gitlab-Event: Deployment Hook { "object_kind": "deployment", "status": "success", + "status_changed_at":"2021-04-28 21:50:00 +0200", "deployable_id": 796, "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", "environment": "staging", diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index f9f61de9d6b..f39c34ccc0a 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,40 +4,38 @@ group: Ecosystem 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 --- -# YouTrack Service **(FREE)** +# YouTrack service **(FREE)** -JetBrains [YouTrack](https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Documentation.html) is a web-based issue tracking and project management platform. +JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project +management platform. -You can configure YouTrack as an [External Issue Tracker](../../../integration/external-issue-tracker.md) in GitLab. +You can configure YouTrack as an +[external issue tracker](../../../integration/external-issue-tracker.md) in GitLab. -## Enable the YouTrack integration +To enable the YouTrack integration in a project: -To enable YouTrack integration in a project: +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **YouTrack**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: + - **Project URL**: The URL to the project in YouTrack. + - **Issue URL**: The URL to view an issue in the YouTrack project. + The URL must contain `:id`. GitLab replaces `:id` with the issue number. +1. Select **Save changes** or optionally select **Test settings**. -1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page. -1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below. +After you configure and enable YouTrack, a link appears on the GitLab +project pages. This link takes you to the appropriate YouTrack project. - | Field | Description | - |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +Learn more about the steps and consequences of disabling GitLab issues in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). -1. Click the **Save changes** button. +## Reference YouTrack issues in GitLab -Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. +You can reference issues in YouTrack using `<PROJECT>-<ID>` (for example `YT-101`, `Api_32-143` or `gl-030`) where: -## Disable the internal issue tracker +- `<PROJECT>` starts with a letter and is followed by letters, numbers, or underscores. +- `<ID>` is a number. -To disable the internal issue tracker in a project: - -1. Navigate to the project's **Settings > General** page. -1. Expand the [permissions section](../settings/index.md#sharing-and-permissions) and switch the **Issues** toggle to disabled. - -## Referencing YouTrack issues in GitLab - -Issues in YouTrack can be referenced as `<PROJECT>-<ID>`. `<PROJECT>` -must start with a letter and is followed by letters, numbers, or underscores. -`<ID>` is a number. An example reference is `YT-101`, `Api_32-143` or `gl-030`. - -References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked to the YouTrack issue URL. -For more information, see the [External Issue Tracker](../../../integration/external-issue-tracker.md) documentation. +References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked +to the YouTrack issue URL. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 5ddf98d4560..e1b6956f873 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -343,11 +343,10 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - [Deployed behind the `board_new_lists` and `iteration_board_lists` feature flags](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57439) in GitLab 13.11. +> - [Deployed behind the `board_new_list` and `iteration_board_lists` feature flags](../feature_flags.md), enabled by default. > - Enabled on GitLab.com. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_lists`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** +> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** There can be [risks when disabling released features](../feature_flags.md#risks-when-disabling-released-features). diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index f5eb8dd5a4d..2a003e68a73 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -31,7 +31,7 @@ to be enabled: - For self-managed instances, a GitLab administrator must have [enabled LFS globally](../../../administration/lfs/index.md). - For both GitLab.com and self-managed instances: LFS must be enabled for the project itself. - If enabled globally, LFS will be enabled by default to all projects. To enable LFS on the + If enabled globally, LFS is enabled by default to all projects. To enable LFS on the project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions** and enable **Git Large File Storage**. @@ -56,7 +56,7 @@ Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned - From GitLab 13.1, Design filenames are limited to 255 characters. - Design Management data [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. -- Design Management data [won't be deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) +- Design Management data [isn't deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) when an issue is deleted. - From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). @@ -102,19 +102,19 @@ the clipboard by simultaneously clicking <kbd>Control</kbd> + <kbd>Command</kbd> Copy-and-pasting has some limitations: -- You can paste only one image at a time. When copy/pasting multiple files, only the first one will be uploaded. -- All images will be converted to `png` format under the hood, so when you want to copy/paste `gif` file, it will result in broken animation. -- If you are pasting a screenshot from the clipboard, it will be renamed to `design_<timestamp>.png` +- You can paste only one image at a time. When copy/pasting multiple files, only the first one is uploaded. +- All images are converted to `png` format under the hood, so when you want to copy/paste `gif` file, it results in broken animation. +- If you are pasting a screenshot from the clipboard, it is renamed to `design_<timestamp>.png` - Copy/pasting designs is not supported on Internet Explorer. -Designs with the same filename as an existing uploaded design will create a new version -of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, +Designs with the same filename as an existing uploaded design create a new version +of the design, and replaces the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design also creates a new version, provided the filenames are the same. ### Skipped designs -Designs with the same filename as an existing uploaded design _and_ whose content has not changed will be skipped. -This means that no new version of the design will be created. When designs are skipped, you will be made aware via a warning +Designs with the same filename as an existing uploaded design _and_ whose content has not changed are skipped. +This means that no new version of the design is created. When designs are skipped, you are made aware via a warning message on the Issue. ## Viewing designs @@ -198,7 +198,7 @@ Different discussions have different pin numbers:  -From GitLab 12.5 on, new discussions will be outputted to the issue activity, +From GitLab 12.5 on, new discussions are outputted to the issue activity, so that everyone involved can participate in the discussion. ## Resolve Design threads @@ -214,13 +214,13 @@ There are two ways to resolve/unresolve a Design thread:  1. Design threads can also be resolved or unresolved in their threads by using a checkbox. - When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve + When replying to a comment, there is a checkbox that you can click in order to resolve or unresolve the thread once published:  -Note that your resolved comment pins will disappear from the Design to free up space for new discussions. -However, if you need to revisit or find a resolved discussion, all of your resolved threads will be +Note that your resolved comment pins disappear from the Design to free up space for new discussions. +However, if you need to revisit or find a resolved discussion, all of your resolved threads are available in the **Resolved Comment** area at the bottom of the right sidebar. ## Add to dos for designs @@ -247,7 +247,7 @@ somewhere with: See https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png ``` -This will be rendered as: +This is rendered as: > See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) diff --git a/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png b/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png Binary files differdeleted file mode 100644 index 8996490ae63..00000000000 --- a/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_issue.png b/doc/user/project/issues/img/delete_issue.png Binary files differdeleted file mode 100644 index 87ea65956fc..00000000000 --- a/doc/user/project/issues/img/delete_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_issue_v13_11.png b/doc/user/project/issues/img/delete_issue_v13_11.png Binary files differnew file mode 100644 index 00000000000..d9905012eab --- /dev/null +++ b/doc/user/project/issues/img/delete_issue_v13_11.png diff --git a/doc/user/project/issues/img/issue_weight.png b/doc/user/project/issues/img/issue_weight.png Binary files differdeleted file mode 100644 index 3800b5940b8..00000000000 --- a/doc/user/project/issues/img/issue_weight.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..842c154ea49 --- /dev/null +++ b/doc/user/project/issues/img/issue_weight_v13_11.png diff --git a/doc/user/project/issues/img/merge_request_closes_issue.png b/doc/user/project/issues/img/merge_request_closes_issue.png Binary files differdeleted file mode 100644 index 6fd27738843..00000000000 --- a/doc/user/project/issues/img/merge_request_closes_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png b/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png Binary files differnew file mode 100644 index 00000000000..26b42239c12 --- /dev/null +++ b/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png Binary files differdeleted file mode 100644 index 97d93620b2a..00000000000 --- a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png Binary files differnew file mode 100644 index 00000000000..4612ae254d4 --- /dev/null +++ b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2963555869c..3af6c528db9 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -67,7 +67,7 @@ To access additional actions, select the vertical ellipsis - To create a new issue in the same project, select **New issue** in the dropdown menu. -- If you are not the issue author, you can [submit an abuse report](../../abuse_reports.md). +- If you are not the issue author, you can [submit an abuse report](../../report_abuse.md). Select **Report abuse** in the dropdown menu. ### To Do @@ -101,7 +101,7 @@ assigned to them if they created the issue themselves. Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. -In [GitLab Starter](https://about.gitlab.com/pricing/), you can +To help with this, you can use GitLab to [assign multiple people](multiple_assignees_for_issues.md) to an issue. ### Epic **(PREMIUM)** diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index b10debf9888..8f17f399cb0 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -7,22 +7,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue weight **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. When you have a lot of issues, it can be hard to get an overview. -By adding a weight to each issue, you can get a better idea of how much time, -value or complexity a given issue has or costs. +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. (The database stores a 4-byte value, so the -upper bound is essentially limitless). +upper bound is essentially limitless.) You can remove weight from an issue as well. This value appears on the right sidebar of an individual issue, as well as -in the issues page next to a distinctive balance scale icon. +in the issues page next to a weight icon (**{weight}**). As an added bonus, you can see the total sum of all issues on the milestone page. - + diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index dafc0e6ba02..9e8a75743a7 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -62,28 +62,31 @@ When you're creating a new issue, these are the fields you can fill in: - Checkbox to make the issue confidential - Assignee - Weight -- Epic **(PREMIUM)** +- [Epic](../../group/epics/index.md) - Due date - Milestone - Labels -### New issue from the group-level Issue Tracker +### New issue from the group-level issue tracker -Go to the Group dashboard and click **Issues** in the sidebar to visit the Issue Tracker -for all projects in your Group. Select the project you'd like to add an issue for -using the dropdown button at the top-right of the page. +To visit the issue tracker for all projects in your group: - +1. Go to the group dashboard. +1. In the left sidebar, select **Issues**. +1. In the top-right, select the **Select project to create issue** button. +1. Select the project you'd like to create an issue for. The button now reflects the selected + project. +1. Select the button to create an issue in the selected project. + + The project you selected most recently becomes the default for your next visit. This should save you a lot of time and clicks, if you mostly create issues for the same project. - - ### New issue via Service Desk Enable [Service Desk](../service_desk.md) for your project and offer email support. -By doing so, when your customer sends a new email, a new issue can be created in +Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there. ### New issue via email @@ -119,21 +122,16 @@ older format is still supported, allowing existing aliases or contacts to contin To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external -HTML page, or create issues with certain +HTML page to create issues with certain fields prefilled. -The title, description, description template, and confidential fields can be prefilled -using this method. You cannot pre-fill both the description and description template -fields in the same URL because a description template also populates the description -field. - | Field | URL Parameter Name | Notes | |----------------------|-----------------------|-------------------------------------------------------| | title | `issue[title]` | | -| description | `issue[description]` | | -| description template | `issuable_template` | | -| issue type | `issue[issue_type]` | Either `incident` or `issue` | -| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential | +| description | `issue[description]` | Cannot be used at the same time as `issuable_template`. | +| description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. | +| issue type | `issue[issue_type]` | Either `incident` or `issue`. | +| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential. | Follow these examples to form your new issue URL with prefilled fields. @@ -144,6 +142,58 @@ Follow these examples to form your new issue URL with prefilled fields. - For a new issue in the GitLab Community Edition project with a pre-filled title, a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` +## Bulk edit issues at the project level + +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + +Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. + +When bulk editing issues in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- [Epic](../../group/epics/index.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) +- [Health status](#health-status) +- Notification subscription +- [Iteration](../../group/iterations/index.md) + +To update multiple project issues at the same time: + +1. In a project, go to **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit issues at the group level + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + +Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. + +When bulk editing issues in a group, you can edit the following attributes: + +- [Epic](../../group/epics/index.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) +- [Health status](#health-status) +- [Iteration](../../group/iterations/index.md) + +To update multiple project issues at the same time: + +1. In a group, go to **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + ## Moving issues Moving an issue copies it to the target project, and closes it in the originating project. @@ -207,7 +257,7 @@ description, issues `#4` and `#6` are closed automatically when the MR is merged Using `Related to` flags `#5` as a [related issue](related_issues.md), but is not closed automatically. - + If the issue is in a different repository than the MR, add the full URL for the issue(s): @@ -278,12 +328,10 @@ of your installation. ## Deleting issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2982) in GitLab 8.6. - Users with [project owner permission](../../permissions.md) can delete an issue by -editing it and clicking on the delete button. +editing it and selecting **Delete issue**. - + ## Promote an issue to an epic **(PREMIUM)** @@ -321,7 +369,7 @@ in a comment or description field. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). +To enable it, you need to enable [Action Cable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). ## Similar issues @@ -354,5 +402,4 @@ This marks issues as progressing as planned or needs attention to keep on schedu After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. -You can then see issue statuses in the issues list and the -[epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). +You can then see issue statuses in the issues list and the epic tree. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index fd5045f2e93..0cb5b5d993e 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Labels +# Labels **(FREE)** As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging to keep track of those items. Especially as your organization grows from just a few people to diff --git a/doc/user/project/members/img/add_user_give_permissions_v13_8.png b/doc/user/project/members/img/add_user_give_permissions_v13_8.png Binary files differdeleted file mode 100644 index 1916d056a52..00000000000 --- a/doc/user/project/members/img/add_user_give_permissions_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png Binary files differdeleted file mode 100644 index a6dddec3fb7..00000000000 --- a/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_imported_members_v13_9.png b/doc/user/project/members/img/add_user_imported_members_v13_9.png Binary files differdeleted file mode 100644 index e40240df2b2..00000000000 --- a/doc/user/project/members/img/add_user_imported_members_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_list_members_v13_9.png b/doc/user/project/members/img/add_user_list_members_v13_9.png Binary files differdeleted file mode 100644 index 7a07ea01d14..00000000000 --- a/doc/user/project/members/img/add_user_list_members_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_search_people_v13_8.png b/doc/user/project/members/img/add_user_search_people_v13_8.png Binary files differdeleted file mode 100644 index e9aa58512ab..00000000000 --- a/doc/user/project/members/img/add_user_search_people_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png Binary files differdeleted file mode 100644 index aa2aaf071e1..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_groups_tab_v13_9.png b/doc/user/project/members/img/project_groups_tab_v13_9.png Binary files differdeleted file mode 100644 index d1b6a640341..00000000000 --- a/doc/user/project/members/img/project_groups_tab_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png Binary files differdeleted file mode 100644 index 99be996c03e..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 2993849e0e6..7dc1a9c612f 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -6,19 +6,75 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Members of a project -You can manage the groups and users and their access levels in all of your -projects. You can also personalize the access level you give each user, -per-project. +Members are the users and groups who have access to your project. -You should have Maintainer or Owner [permissions](../../permissions.md) to add -or import a new user to your project. +Each member gets a role, which determines what they can do in the project. -To view, edit, add, and remove project's members, go to your -project's **Members**. +## Add users to a project + +Add users to a project so they become members and have permission +to perform actions. + +Prerequisite: + +- You must have maintainer or owner [permissions](../../permissions.md). + +To add a user to a project: + +1. Go to your project and select **Members**. +1. On the **Invite member** tab, under **GitLab member of Email address**, type the username or email address. +1. Select a [role](../../permissions.md). +1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. Select **Invite**. + +If the user has a GitLab account, they are added to the members list. +If you used an email address, the user receives an email. + +## Add groups to a project + +When you assign a group to a project, each user in the group gets access to the project, +based on the role they're assigned in the group. However, the user's access is also +limited by the maximum role you choose when you invite the group. + +Prerequisite: + +- You must have maintainer or owner [permissions](../../permissions.md). + +To add groups to a project: + +1. Go to your project and select **Members**. +1. On the **Invite group** tab, under **Select a group to invite**, choose a group. +1. Select the highest max [role](../../permissions.md) for users in the group. +1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. Select **Invite**. + +The members of the group are not displayed on the **Members** tab. +The **Members** tab shows: + +- Members who are directly assigned to the project. +- If the project was created in a group [namespace](../../group/index.md#namespaces), members of that group. + +## Import users from another project + +You can import another project's users to your own project. Users +retain the same permissions as the project you import them from. + +Prerequisite: + +- You must have maintainer or owner [permissions](../../permissions.md). + +To import users: + +1. Go to your project and select **Members**. +1. On the **Invite member** tab, at the bottom of the panel, select **Import**. +1. Select the project. You can view only the projects for which you're a maintainer. +1. Select **Import project members**. + +A success message is displayed and the new members are now displayed in the list. ## Inherited membership -When your project belongs to the group, group members inherit the membership and permission +When your project belongs to a group, group members inherit the membership and permission level for the project from the group.  @@ -70,43 +126,6 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last  -## Add a user - -Right next to **People**, start typing the name or username of the user you -want to add. - - - -Select the user and the [permission level](../../permissions.md) -that you'd like to give the user. You can add more than one user at a time. -The Owner role can only be assigned at the group level. - - - -Once done, select **Add users to project** and they are immediately added to -your project with the permissions you gave them above. - - - -From there on, you can either remove an existing user or change their access -level to the project. - -## Import users from another project - -You can import another project's users in your own project by hitting the -**Import members** button on the upper right corner of the **Members** menu. - -In the dropdown menu, you can see only the projects you are Maintainer on. - - - -Select the one you want and hit **Import project members**. A flash message -displays, notifying you that the import was successful, and the new members -are now in the project's members list. Notice that the permissions that they -had on the project you imported from are retained. - - - ## Invite people using their e-mail address NOTE: @@ -235,8 +254,7 @@ requests they are currently assigned or leave the assignments as they are. To remove a member from a project: -1. In a project, go to **{users}** **Members**. -1. Click the **Delete** **{remove}** button next to a project member you want to remove. - A **Remove member** modal appears. -1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. -1. Click **Remove member**. +1. Go to your project and select **Members**. +1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. +1. Select **Remove member**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 8338c17f4ba..085e4db0b94 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,7 +4,7 @@ group: unassigned 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 --- -# Share Projects with other Groups +# Share projects with other groups You can share projects with other [groups](../../group/index.md). This makes it possible to add a group of users to a project with a single action. @@ -28,22 +28,14 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Members**. - -  - 1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. 1. Optionally, select an expiring date. 1. Click **Invite**. 1. After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. - -  - - The project is listed on the group dashboard. -  - Note that you can only share a project with: - groups for which you have an explicitly defined membership diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png Binary files differindex 306bf57354d..306bf57354d 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png +++ b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png diff --git a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_7.png b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png Binary files differindex 669148a41d8..669148a41d8 100644 --- a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_7.png +++ b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png Binary files differindex a6636f0bc7f..a6636f0bc7f 100644 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png +++ b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png Binary files differindex c5596b965ff..c5596b965ff 100644 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png +++ b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md new file mode 100644 index 00000000000..ac48e44da52 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/index.md @@ -0,0 +1,145 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +--- + +# Merge request approvals **(FREE)** + +> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. + +You can configure your merge requests so that they must be approved before +they can be merged. You can do this by creating [rules](rules.md) or by specifying +a list of users who act as [code owners](../../code_owners.md) for specific files. + +You can configure merge request approvals for each project. In higher GitLab tiers, +Administrators of self-managed GitLab instances can configure approvals +[for the entire instance](../../../admin_area/merge_requests_approvals.md). + +## How approvals work + +With [merge request approval rules](rules.md), you can set the minimum number of +required approvals before work can merge into your project. You can also extend these +rules to define what types of users can approve work. Some examples of rules you can create include: + +- Users with specific permissions can always approve work. +- [Code owners](../../code_owners.md) can approve work for files they own. +- Users with specific permissions can approve work, + [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties) + to the repository. +- Users with specific permissions can be allowed or denied the ability + to [override approval rules on a specific merge request](rules.md#edit-or-override-merge-request-approval-rules). + +You can also configure additional [settings for merge request approvals](settings.md) +for more control of the level of oversight and security your project needs, including: + +- [Prevent users from overriding a merge request approval rule.](settings.md#prevent-overrides-of-default-approvals) +- [Reset approvals when new code is pushed.](settings.md#reset-approvals-on-push) +- Allow (or disallow) [authors and committers](settings.md) to approve their own merge requests. +- [Require password authentication when approving.](settings.md#require-authentication-for-approvals) +- [Require security team approval.](settings.md#security-approvals-in-merge-requests) + +You can configure your merge request approval rules and settings through the GitLab +user interface or [with the API](../../../../api/merge_request_approvals.md). + +## Approve a merge request + +When an [eligible approver](rules.md#eligible-approvers) visits an open merge request, +GitLab displays one of these buttons after the body of the merge request: + +- **Approve**: The merge request doesn't yet have the required number of approvals. +- **Approve additionally**: The merge request has the required number of approvals. +- **Revoke approval**: The user viewing the merge request has already approved + the merge request. + +Eligible approvers can also use the `/approve` +[quick action](../../../project/quick_actions.md) when adding a comment to +a merge request. + +After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge +unless it's blocked for another reason. Merge requests can be blocked by other problems, +such as merge conflicts, [pending discussions](../../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), +or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). + +To prevent merge request authors from approving their own merge requests, +enable [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) +in your project's settings. + +If you enable [approval rule overrides](settings.md#prevent-overrides-of-default-approvals), +merge requests created before a change to default approval rules are not affected. +The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +## Optional approvals + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. + +GitLab allows all users with Developer or greater [permissions](../../../permissions.md) +to approve merge requests. Approvals in GitLab Free are optional, and don't prevent +a merge request from merging without approval. + +## Required approvals **(PREMIUM)** + +> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9. + +Required approvals enforce code reviews by the number and type of users you specify. +Without the approvals, the work cannot merge. Required approvals enable multiple use cases: + +- Enforce review of all code that gets merged into a repository. +- Specify reviewers for a given proposed code change, and a minimum number + of reviewers, through [Approval rules](rules.md). +- Specify categories of reviewers, such as backend, frontend, quality assurance, or + database, for all proposed code changes. +- Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), + to determine who should review the work. +- [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) + before merging code that could introduce a vulnerability. **(ULTIMATE)** + +## Notify external services **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. +> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create an external approval rule to integrate approvals with third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. +The users of the third-party tools can then approve merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. +You can modify your external approval rules +[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). + +The lack of an external approval doesn't block the merging of a merge request. + +When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, +changes to default approval rules will **not** be applied to existing +merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +To learn more about use cases, feature discovery, and development timelines, +see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## Related links + +- [Merge request approvals API](../../../../api/merge_request_approvals.md) +- [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations + +<!-- ## 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. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md new file mode 100644 index 00000000000..32f0160771f --- /dev/null +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -0,0 +1,232 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval rules + +Approval rules define how many [approvals](index.md) a merge request must receive before it can +be merged, and which users should do the approving. You can define approval rules: + +- [As project defaults](#add-an-approval-rule). +- [Per merge request](#edit-or-override-merge-request-approval-rules). +- [At the instance level](../../../admin_area/merge_requests_approvals.md) + +If you don't define a [default approval rule](#add-an-approval-rule), +any user can approve a merge request. Even if you don't define a rule, you can still +enforce a [minimum number of required approvers](settings.md) in the project's settings. + +You can define a single rule to approve merge requests from among the available +rules, or you can select [multiple approval rules](#add-multiple-approval-rules). + +Merge requests that target a different project, such as from a fork to the upstream project, +use the default approval rules from the target (upstream) project, not the source (fork). + +## Add an approval rule + +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. 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` + creates a required rule. +1. To add users or groups as approvers, search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. GitLab suggests approvers based on + previous authors of the files changed by the merge request. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + +1. Select **Add approval rule**. + +Users of GitLab Premium and higher tiers can create [additional approval rules](#add-multiple-approval-rules). + +Your configuration for approval rule overrides determines if the new rule is applied +to existing merge requests: + +- If [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, + changes to these default rules are not applied to existing merge requests, except for + changes to the [target branch](#approvals-for-protected-branches) of the rule. +- If approval rule overrides are not allowed, all changes to default rules + are applied to existing merge requests. Any approval rules that were previously + manually [overridden](#edit-or-override-merge-request-approval-rules) during the + period when approval rule overrides where allowed, are not modified. + +## Edit an approval rule + +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. (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: + - *To add users or groups as approvers,* search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + + - *To remove users or groups,* identify the group or user to remove, and + select **{remove}** **Remove**. +1. Select **Update approval rule**. + +## Add multiple approval rules **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10. + +In GitLab Premium and higher tiers, you can enforce multiple approval rules on a +merge request, and multiple default approval rules for a project. If your tier +supports multiple default rules: + +- When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule + for a project, GitLab displays the **Add approval rule** button even after a rule is defined. +- When editing or overriding multiple approval rules + [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab + displays the **Add approval rule** button even after a rule is defined. + +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: + + + +## Eligible approvers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. + +To be eligible as an approver for a project, a user must be a member of one or +more of these: + +- The project. +- The project's immediate parent [group](#group-approvers). +- A group that has access to the project via a [share](../../members/share_project_with_groups.md). +- A [group added as approvers](#group-approvers). + +The following users can approve merge requests if they have Developer or +higher [permissions](../../../permissions.md): + +- Users added as approvers at the project or merge request level. +- Users who are [Code owners](#code-owners-as-eligible-approvers) of the files + changed in the merge request. + +To show who has participated in the merge request review, the Approvals widget in +a merge request displays a **Commented by** column. This column lists eligible approvers +who commented on the merge request. It helps authors and reviewers identify who to +contact with questions about the merge request's content. + +If the number of required approvals is greater than the number of assigned approvers, +approvals from other users with Developer [permissions](../../../permissions.md) or higher +in the project counts toward meeting the required number of approvals, even if the +users were not explicitly listed in the approval rules. + +### Group approvers + +You can add a group of users as approvers, but those users count as approvers only if +they have direct membership to the group. In the future, group approvers may be +restricted to only groups [with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). + +A user's membership in an approvers group affects their individual ability to +approve in these ways: + +- A user already part of a group approver who is later added as an individual approver + counts as one approver, and not two. +- Merge request authors do not count as eligible approvers on their own merge requests by default. + To change this behavior, disable the + [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) + project setting. +- Committers to merge requests can approve a merge request. To change this behavior, enable the + [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) + project setting. + +### Code owners as eligible approvers + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. + +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 **Any eligible user** and select the number of approvals required: + +  + +You can also +[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) +for protected branches. **(PREMIUM)** + +## Merge request approval segregation of duties + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to GitLab Premium in 13.9. + +You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +permission to approve merge requests before they can merge to a protected branch. +Some users (like managers) may not need permission to push or merge code, but still need +oversight on proposed work. To enable approval permissions for these users without +granting them push access: + +1. [Create a new group](../../../group/index.md#create-a-group). +1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), + and select the Reporter role for the user. +1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-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**. +1. [Add the group](../../../group/index.md#create-a-group) to the permission list. + +  + +### Edit or override merge request approval rules + +By default, the merge request author (or a user with sufficient [permissions](../../../permissions.md)) +can edit the approval rule listed in a merge request. When editing an approval rule +on a merge request, you can either add or remove approvers: + +1. In the merge request, find the **Approval rules section**. +1. When creating a new merge request, scroll to the **Approval Rules** section, + and add or remove your desired approval rules before selecting **Create merge request**. +1. When viewing an existing merge request: + 1. Select **Edit**. + 1. Scroll to the **Approval Rules** section. + 1. Add or remove your desired approval rules. + 1. Select **Save changes**. + +Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) +to prevent users from overriding approval rules for merge requests. + +## Configure optional approval rules + +Merge request approvals can be optional for projects where approvals are +appreciated, but not required. To make an approval rule optional: + +- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `0`. +- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) + to set the `approvals_required` attribute to `0`. + +## Approvals for protected branches **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8. + +Approval rules are often relevant only to specific branches, like your +[default branch](../../repository/branches/default.md). To configure an +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. Select a **Target branch**: + - To protect all branches, select **Any branch**. + - To select a specific branch, select it from the list: + +  +1. To enable this configuration, read + [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md new file mode 100644 index 00000000000..8769f6a7470 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -0,0 +1,125 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval settings + +You can configure the settings for [merge request approvals](index.md) to +ensure the approval rules meet your use case. You can also configure +[approval rules](rules.md), which define the number and type of users who must +approve work before it's merged. Merge request approval settings define how +those rules are applied as a merge request moves toward completion. + +## Edit merge request approval settings + +To view or edit merge request approval settings: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. + +In this section of general settings, you can configure the settings described +on this page. + +## Prevent overrides of default approvals + +By default, users can override the approval rules you [create for a project](rules.md) +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 users from modifying MR approval rules in merge requests** checkbox. +1. Select **Save changes**. + +TODO This change affects all open merge requests. + +## Reset approvals on push + +By default, an approval on a merge request remains in place, even if you add more changes +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 **Require new approvals when new commits are added to an MR** checkbox. +1. Select **Save changes**. + +Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) +However, approvals are reset if the target branch is changed. + +## Prevent authors from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. + +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 MR approval by the author** checkbox. +1. Select **Save changes**. + +Authors can edit the approval rule in an individual merge request and override +this setting, unless you configure one of these options: + +- [Prevent overrides of default approvals](#prevent-overrides-of-default-approvals) at + the project level. +- *(Self-managed instances only)* Prevent overrides of default approvals + [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured + at the instance level, you can't edit this setting at the project or individual + merge request levels. + +## Prevent committers from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +By default, users who commit to a merge request can still approve it. At both +the project level or [instance level](../../../admin_area/merge_requests_approvals.md) +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 MR approvals from users who make commits to the MR** checkbox. + 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. +1. Select **Save changes**. + +Even with this configuration, [code owners](../../code_owners.md) who contribute +to a merge request can approve merge requests that affect files they own. + +To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), +read the official Git documentation for an explanation. + +## Require authentication for approvals + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. + +You can force potential approvers to first authenticate with a password. This +permission enables an electronic signature for approvals, such as the one defined by +[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)): + +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 for approvals** checkbox. +1. Select **Save changes**. + +## Security approvals in merge requests **(ULTIMATE)** + +You can require that a member of your security team approves a merge request if a +merge request could introduce a vulnerability. To learn more, see +[Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). + +## Related links + +- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) +- [Compliance Dashboard](../../../compliance/compliance_dashboard/index.md) +- [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 76913351283..b33919c7fbe 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -64,7 +64,7 @@ using Docker-in-Docker. 1. First, set up GitLab Runner with a [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -1. Configure the default Browser Performance Testing CI job as follows in your `.gitlab-ci.yml` file: +1. Configure the default Browser Performance Testing CI/CD job as follows in your `.gitlab-ci.yml` file: ```yaml include: @@ -75,17 +75,19 @@ using Docker-in-Docker. URL: https://example.com ``` -NOTE: -For versions before 12.4, see the information for [older GitLab versions](#gitlab-versions-123-and-older). -If you are using a Kubernetes cluster, use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) -instead. +WARNING: +In GitLab 14.0 and later, the job [is scheduled to be renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) +from `performance` to `browser_performance`. -The above example creates a `performance` job in your CI/CD pipeline and runs -sitespeed.io against the webpage you defined in `URL` to gather key metrics. +The above example: -The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 -or older, you must [add the configuration manually](#gitlab-versions-123-and-older) +- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you + defined in `URL` to gather key metrics. +- Uses a template that doesn't work with Kubernetes clusters. If you are using a Kubernetes cluster, + use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) + instead. +- Uses a CI/CD template that is included in all GitLab installations since 12.4. If you are using + GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) @@ -181,63 +183,62 @@ performance: URL: environment_url.txt ``` -### GitLab versions 12.3 and older +### GitLab versions 13.2 and earlier -Browser Performance Testing has gone through several changes since it's introduction. +Browser Performance Testing has gone through several changes since its introduction. In this section we detail these changes and how you can run the test based on your GitLab version: +- In 13.2 the feature was renamed from `Performance` to `Browser Performance` with additional + template CI/CD variables. - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). -- In 13.2 the feature was renamed from `Performance` to `Browser Performance` with -additional template CI/CD variables. The job name in the template is still `performance` -for compatibility reasons, but may be renamed to match in a future iteration. - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: -```yaml -performance: - stage: performance - image: docker:git - variables: - URL: https://example.com - SITESPEED_VERSION: 14.1.0 - SITESPEED_OPTIONS: '' - services: - - docker:stable-dind - script: - - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS - - mv sitespeed-results/data/performance.json performance.json - artifacts: - paths: - - performance.json - - sitespeed-results/ - reports: - performance: performance.json -``` + ```yaml + performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + SITESPEED_VERSION: 14.1.0 + SITESPEED_OPTIONS: '' + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ + reports: + performance: performance.json + ``` - For 11.4 and earlier the job should be defined as follows: -```yaml -performance: - stage: performance - image: docker:git - variables: - URL: https://example.com - services: - - docker:stable-dind - script: - - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL - - mv sitespeed-results/data/performance.json performance.json - artifacts: - paths: - - performance.json - - sitespeed-results/ -``` + ```yaml + performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ + ``` Upgrading to the latest version and using the templates is recommended, to ensure you receive the latest updates, including updates to the sitespeed.io versions. diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md new file mode 100644 index 00000000000..adcf4518209 --- /dev/null +++ b/doc/user/project/merge_requests/changes.md @@ -0,0 +1,151 @@ +--- +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: index, reference +--- + +# Changes tab in merge requests + +The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, +shows the changes to files between branches or commits. This view of changes to a +file is also known as a **diff**. By default, the diff view compares the file in the +merge request branch and the file in the target branch. + +The diff view includes the following: + +- The file's name and path. +- The number of lines added and deleted. +- Buttons for the following options: + - Toggle comments for this file; useful for inline reviews. + - Edit the file in the merge request's branch. + - Show full file, in case you want to look at the changes in context with the rest of the file. + - View file at the current commit. + - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). +- The changed lines, with the specific changes highlighted. + + + +## Merge request diff file navigation + +When reviewing changes in the **Changes** tab, the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list. + + + +## Collapsed files in the Changes view + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. + +When you review changes in the **Changes** tab, files with a large number of changes are collapsed +to improve performance. When files are collapsed, a warning appears at the top of the changes. +Select **Expand file** on any file to view the changes for that file. + +## File-by-file diff navigation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. + +For larger merge requests, consider reviewing one file at a time. To enable this feature: + +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Select **Save changes**. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can select **Prev** and **Next** to view other changed files. + + + +In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change +this behavior, you can do so from your **User preferences** (as explained above) or directly in a +merge request: + +1. Go to the merge request's **Changes** tab. +1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select or clear the checkbox **Show one file at a time** to change the setting accordingly. + +This change overrides the choice you made in your user preferences and persists until you clear your +browser's cookies or change this behavior again. + +## Merge requests commit navigation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To seamlessly navigate among commits in a merge request: + +1. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons below the tab buttons. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + + +## Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change select the +**Expand up** or **Expand down** icons. You can also select **Show unchanged lines** +to expand the entire file. + + + +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a +merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the +entire content by selecting **Show file contents**. + +## Ignore whitespace changes in Merge Request diff view + +If you select the **Hide whitespace changes** button, you can see the diff +without whitespace changes (if there are any). This is also working when on a +specific commit page. + + + +NOTE: +You can append `?w=1` while on the diffs page of a merge request to ignore any +whitespace changes. + +## Mark files as viewed + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. +> - Deployed behind a feature flag, enabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** + +When reviewing a merge request with many files multiple times, it may be useful to the reviewer +to focus on new changes and ignore the files that they have already reviewed and don't want to +see anymore unless they are changed again. + +To mark a file as viewed: + +1. Go to the merge request's **Diffs** tab. +1. On the right-top of the file, locate the **Viewed** checkbox. +1. Select it to mark the file as viewed. + +Once checked, the file remains marked for that reviewer unless there are newly introduced +changes to its content or the checkbox is unchecked. + +### Enable or disable file views **(FREE SELF)** + +The file view feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:local_file_reviews) +``` + +To disable it: + +```ruby +Feature.disable(:local_file_reviews) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index f531cd52af1..eaeef12444e 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -16,7 +16,7 @@ with a **Cherry-pick** button in merge requests and commit details. After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. - + After you click that button, a modal displays a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) @@ -32,7 +32,7 @@ where you can choose to either: 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. - + Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 0fe1b9801cc..284d66dd591 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -53,20 +53,21 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example:  -To enable this feature, a GitLab administrator can run the following in a +To disable this feature, a GitLab administrator can run the following in a [Rails console](../../../administration/operations/rails_console.md): ```ruby # For the instance -Feature.enable(:codequality_mr_diff) +Feature.disable(:codequality_mr_diff) # For a single project -Feature.enable(:codequality_mr_diff, Project.find(<project id>)) +Feature.disable(:codequality_mr_diff, Project.find(<project id>)) ``` ## Use cases @@ -519,7 +520,7 @@ to change the default configuration, **not** a `.codequality.yml` file. If you u the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. -### No Code Quality report is displayed in a Merge Request +### No Code Quality report is displayed in a merge request This can be due to multiple reasons: @@ -531,7 +532,7 @@ This can be due to multiple reasons: nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. -- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the Merge Request widget to have no base report for comparison. +- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 3a5a581198b..ce1dac0a96b 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -3,14 +3,14 @@ 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: howto -description: "How to create Merge Requests in GitLab." +description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- # How to create a merge request **(FREE)** Before creating a merge request, read through an -[introduction to Merge Requests](getting_started.md) +[introduction to merge requests](getting_started.md) to familiarize yourself with the concept, the terminology, and to learn what you can do with them. @@ -21,16 +21,16 @@ or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through- This document describes the several ways to create a merge request. When you start a new merge request, regardless of the method, -you are taken to the [**New Merge Request** page](#new-merge-request-page) +you are taken to the [**New merge request** page](#new-merge-request-page) to fill it with information about the merge request. If you push a new branch to GitLab, also regardless of the method, -you can click the [**Create Merge Request**](#create-merge-request-button) +you can click the [**Create merge request**](#create-merge-request-button) button and start a merge request from there. -## New Merge Request page +## New merge request page -On the **New Merge Request** page, start by filling in the title and description +On the **New merge request** page, start by filling in the title and description for the merge request. If commits already exist on the branch, GitLab suggests a merge request title for you: @@ -43,31 +43,31 @@ merge request title for you: The title is the only field that is mandatory in all cases. From there, you can fill it with information (title, description, -assignee(s), milestone, labels, approvers) and click **Create Merge Request**. +assignee(s), milestone, labels, approvers) and click **Create merge request**. From that initial screen, you can also see all the commits, pipelines, and file changes pushed to your branch before submitting the merge request. - + NOTE: You can push one or more times to your branch in GitLab before creating the merge request. -## Create Merge Request button +## Create merge request button Once you have pushed a new branch to GitLab, visit your repository in GitLab and to see a call-to-action at the top of your screen -from which you can click the button **Create Merge Request**. +from which you can click the button **Create merge request**. - + You can also see the **Create merge request** button in the top-right of the: - **Project** page. - **Repository > Files** page. -- **Merge Requests** page. +- **Merge requests** page. In this case, GitLab uses the most recent branch you pushed changes to as the source branch, and the default branch in the current @@ -90,7 +90,7 @@ Once you have added, edited, or uploaded the file: 1. Click **Commit changes**. If you chose to start a merge request, you are taken to the -[**New Merge Request** page](#new-merge-request-page), from +[**New merge request** page](#new-merge-request-page), from which you can fill it in with information and submit the merge request. The merge request targets the default branch of the repository. @@ -103,8 +103,8 @@ navigate to your project's **Repository > Branches** and click **New branch**. A new branch is created and you can start editing files. -Once committed and pushed, you can click on the [**Create Merge Request**](#create-merge-request-button) -button to open the [**New Merge Request** page](#new-merge-request-page). +Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button) +button to open the [**New merge request** page](#new-merge-request-page). A new merge request is started using the current branch as the source, and the default branch in the current project as the target. @@ -140,7 +140,7 @@ remote: To create a merge request for docs-new-merge-request, visit: remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch ``` -Copy that link and paste it in your browser, and the [**New Merge Request page**](#new-merge-request-page) +Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page) is displayed. There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. @@ -148,20 +148,20 @@ There is also a number of [flags you can add to commands when pushing through th If you didn't push your branch to GitLab through the command line (for example, you used a Git CLI application to push your changes), you can create a merge request through the GitLab UI by clicking -the [**Create Merge Request**](#create-merge-request-button) button. +the [**Create merge request**](#create-merge-request-button) button. ## New merge request from an issue You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). -## New merge request from the Merge Requests page +## New merge request from the merge requests page You can start creating a new merge request by clicking the -**New merge request** button on the **Merge Requests** page in a project. +**New merge request** button on the **merge requests** page in a project. Then choose the source project and branch that contain your changes, and the target project and branch where you want to merge the changes into. Click on **Compare branches and continue** to go to the -[**New Merge Request** page](#new-merge-request-page) and fill in the details. +[**New merge request** page](#new-merge-request-page) and fill in the details. ## New merge request from a fork @@ -169,7 +169,7 @@ After forking a project and applying your local changes, complete the following create a merge request from your fork to contribute back to the main project: 1. Go to **Projects > Your Projects** and select your fork of the repository. -1. In the left menu, go to **Merge Requests**, and click **New Merge Request**. +1. In the left menu, go to **Merge requests**, and click **New merge request**. 1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. 1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. You can set a [default target project](#set-the-default-target-project) to @@ -247,6 +247,6 @@ apply the patches. The target branch can be specified using the [`/target_branch` quick action](../quick_actions.md). If the source branch already exists, the patches are applied on top of it. -## Reviewing and managing Merge Requests +## Reviewing and managing merge requests -Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab. +Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f973d9220f2..5556e54f875 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,13 +4,13 @@ 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 --- -# Export Merge Requests to CSV **(FREE)** +# Export merge requests to CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. -Exporting Merge Requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. +Exporting merge requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. -To export Merge Requests to CSV, navigate to your **Merge Requests** from the sidebar of a project and click **Export to CSV**. +To export merge requests to CSV, navigate to your **Merge requests** from the sidebar of a project and click **Export to CSV**. ## CSV Output diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a030961e219..57850ad7304 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -66,7 +66,7 @@ when you mark a merge request as ready, notifications are triggered to When viewing or searching in your project's merge requests list, you can include or exclude draft merge requests: -1. In your project, select **Merge Requests** from the left sidebar. +1. Go to your project and select **Merge requests**. 1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to filter by merge request status. 1. Click the search box to display a list of filters and select **Draft**, or diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 80bdbce8d2c..68a63aebb90 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -42,14 +42,14 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for Merge Requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) + - Use [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. ## Configuring Fast RSpec Failure -We'll use the following plain RSpec configuration as a starting point. It installs all the +We use the following plain RSpec configuration as a starting point. It installs all the project gems and executes `rspec`, on merge request pipelines only. ```yaml @@ -86,13 +86,13 @@ For illustrative purposes, let's say our Rails app spec suite consists of 100 sp If no Ruby files are changed: -- `rspec-rails-modified-paths-specs` will not run any tests. -- `rspec-complete` will run the full suite of 1000 tests. +- `rspec-rails-modified-paths-specs` does not run any tests. +- `rspec-complete` runs the full suite of 1000 tests. If one Ruby model is changed, for example `app/models/example.rb`, then `rspec-rails-modified-paths-specs` -will run the 100 tests for `example.rb`: +runs the 100 tests for `example.rb`: - If all of these 100 tests pass, then the full `rspec-complete` suite of 1000 tests is allowed to run. -- If any of these 100 tests fail, they will fail quickly, and `rspec-complete` will not run any tests. +- If any of these 100 tests fail, they fail quickly, and `rspec-complete` does not run any tests. The final case saves resources and time as the full 1000 test suite does not run. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 1bb333dcb14..459b8fa56ff 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -3,12 +3,12 @@ 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: index, reference -description: "Getting started with Merge Requests." +description: "Getting started with merge requests." --- -# Getting started with Merge Requests **(FREE)** +# Getting started with merge requests **(FREE)** -A Merge Request (**MR**) is the basis of GitLab as a code +A merge request (**MR**) is the basis of GitLab as a code collaboration and version control. When working in a Git-based platform, you can use branching @@ -25,7 +25,7 @@ avoiding changes to be pushed directly to the default branch without prior reviews, tests, and approvals. When you create a new feature branch, change the files, and push -it to GitLab, you have the option to create a **Merge Request**, +it to GitLab, you have the option to create a **merge request**, which is essentially a _request_ to merge one branch into another. The branch you added your changes into is called _source branch_ @@ -56,7 +56,7 @@ request's page at the top-right side: - [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- Require [approval](merge_request_approvals.md) from your team. **(PREMIUM)** +- [Require approval](approvals/index.md#required-approvals) from your team. **(PREMIUM)** - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -65,24 +65,24 @@ request's page at the top-right side: 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](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews). +- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** -- Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). -- Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). +- Preview continuous integration [pipelines on the merge request widget](reviews/index.md#pipeline-status-in-merge-requests-widgets). +- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready. -- Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. +- Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. +- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). Many of these can be set when pushing changes from the command line, with [Git push options](../push_options.md). -See also other [features associated to merge requests](reviewing_and_managing_merge_requests.md#associated-features). +See also other [features associated to merge requests](reviews/index.md#associated-features). ### Assignee Choose an assignee to designate someone as the person responsible -for the first [review of the merge request](reviewing_and_managing_merge_requests.md). +for the first [review of the merge request](reviews/index.md). Open the drop down box to search for the user you wish to assign, and the merge request is added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). @@ -122,7 +122,7 @@ Requesting a code review is an important part of contributing code. However, dec your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -The Merge Request Reviewers feature enables you to request a review of your work, and +The merge request Reviewers feature enables you to request a review of your work, and see the status of the review. Reviewers help distinguish the roles of the users involved in the merge request. In comparison to an **Assignee**, who is directly responsible for creating or merging a merge request, a **Reviewer** is a team member @@ -138,7 +138,7 @@ When selected, GitLab creates a [to-do list item](../../todos.md) for each revie > - [Feature flag 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](merge_request_approvals.md#approval-rules) +displays the name of the matching [approval rule](approvals/rules.md) below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. This example shows reviewers and approval rules when creating a new merge request: @@ -234,7 +234,7 @@ The feature today works only on merge. Clicking the **Remove source branch** but after the merge request was merged will not automatically retarget a merge request. This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). -## Recommendations and best practices for Merge Requests +## Recommendations and best practices for merge requests - When working locally in your branch, add multiple commits and only push when you're done, so GitLab runs only one pipeline for all the commits pushed diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png Binary files differdeleted file mode 100644 index e2641f48c7a..00000000000 --- a/doc/user/project/merge_requests/img/approve.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png Binary files differdeleted file mode 100644 index bab0cd4e041..00000000000 --- a/doc/user/project/merge_requests/img/approve_additionally.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png b/doc/user/project/merge_requests/img/group_merge_requests_list_view.png Binary files differdeleted file mode 100644 index 7d0756505db..00000000000 --- a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png Binary files differdeleted file mode 100644 index b178d26cf85..00000000000 --- a/doc/user/project/merge_requests/img/remove_approval.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 1fed30dc589..f587ab34d11 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -8,7 +8,6 @@ type: index, reference # Merge requests **(FREE)** Merge requests (MRs) are the way you check source code changes into a branch. - When you open a merge request, you can visualize and collaborate on the code changes before merge. Merge requests include: @@ -18,6 +17,11 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. +Merge requests contain tabs at the top of the page to help you navigate to +important parts of the merge request: **Overview**, **Commits**, **Pipelines**, and **Changes**. + + + To get started, read the [introduction to merge requests](getting_started.md). ## Merge request workflows @@ -29,10 +33,10 @@ For a software developer working in a team: 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md). 1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD. 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). -1. You request the [approval](merge_request_approvals.md) from your manager. +1. You request the [approval](approvals/index.md) from your manager. 1. Your manager: 1. Pushes a commit with their final review. - 1. [Approves the merge request](merge_request_approvals.md). + 1. [Approves the merge request](approvals/index.md). 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. @@ -43,35 +47,13 @@ For a web developer writing a webpage for your company's website: 1. You gather feedback from your reviewers. 1. You preview your changes with [Review Apps](../../../ci/review_apps/index.md). 1. You request your web designers for their implementation. -1. You request the [approval](merge_request_approvals.md) from your manager. +1. You request the [approval](approvals/index.md) from your manager. 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). 1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. -## Merge request navigation tabs at the top - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. - -In GitLab 12.5 and earlier, navigation tabs in merge requests (**Discussion**, -**Commits**, **Pipelines**, and **Changes**) were located after the merge request -widget. - -To facilitate navigation without scrolling, and based on user feedback, the tabs are -now located at the top of the merge request tab. A new **Overview** tab was added, -and next to **Overview** are **Commits**, **Pipelines**, and **Changes**. - - - -This change is behind a feature flag that is enabled by default. For -self-managed instances, it can be disabled through the Rails console by a GitLab -administrator with the following command: - -```ruby -Feature.disable(:mr_tabs_position) -``` - ## Related topics - [Create a merge request](creating_merge_requests.md) -- [Review and manage merge requests](reviewing_and_managing_merge_requests.md) +- [Review and manage merge requests](reviews/index.md) - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 835350ade44..38d6ba062e4 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,416 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, concepts +redirect_to: 'approvals/index.md' --- -# Merge Request Approvals **(FREE)** +This document was moved to [another location](approvals/index.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers. -> - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. - -Code review is an essential practice of every successful project. Approving a -merge request is an important part of the review -process, as it clearly communicates the ability to merge the change. -A [merge request approvals API](../../../api/merge_request_approvals.md) is also available. - -## Optional Approvals - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. - -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Free and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and ensures -maintainers know a change is ready to merge. Approvals in Free are optional, and do -not prevent a merge request from being merged when there is no approval. - -## External approvals **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -When you create an external approval rule, the following merge request actions sends information -about a merge request to a third party service: - -- Create -- Change -- Close - -This action enables use-cases such as: - -- Integration with 3rd party workflow tools, such as [ServiceNow](https://www.servicenow.co.uk/). -- Integration with custom tools designed to approve merge requests from outside of GitLab. - -You can find more information about use-cases, development timelines and the feature discovery in -the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). - -The intention for this feature is to allow those 3rd party tools to approve a merge request similarly to how users current do. - -NOTE: -The lack of an external approval does not block the merging of a merge request. - -You can modify external approval rules through the [REST API](../../../api/merge_request_approvals.md#external-project-level-mr-approvals). - -## Required Approvals **(PREMIUM)** - -> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. -> - Moved to GitLab Premium in 13.9. - -Required approvals enable enforced code review by requiring specified people -to approve a merge request before it can be merged. - -Required approvals enable multiple use cases: - -- Enforcing review of all code that gets merged into a repository. -- Specifying reviewers for a given proposed code change, as well as a minimum number - of reviewers, through [Approval rules](#approval-rules). -- Specifying categories of reviewers, such as backend, frontend, quality assurance, - database, and so on, for all proposed code changes. -- Designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), - determined by the files changed in a merge request. -- [Requiring approval from a security team](#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability.**(ULTIMATE)** - -### Approval Rules - -Approval rules define how many approvals a merge request must receive before it can -be merged, and optionally which users should do the approving. Approvals can be defined: - -- [As project defaults](#adding--editing-a-default-approval-rule). -- [Per merge request](#editing--overriding-approval-rules-per-merge-request). - -If no approval rules are defined, any user can approve a merge request. However, the default -minimum number of required approvers can still be set in the -[settings for merge request approvals](#approval-settings). - -You can opt to define one single rule to approve a merge request among the available rules -or choose more than one with [multiple approval rules](#multiple-approval-rules). - -NOTE: -On GitLab.com, you can add a group as an approver if you're a member of that group or the -group is public. - -#### Eligible Approvers - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. - -The following users can approve merge requests: - -- Users who have been added as approvers at the project or merge request levels with - developer or higher [permissions](../../permissions.md). -- [Code owners](#code-owners-as-eligible-approvers) of the files changed by the merge request - that have developer or higher [permissions](../../permissions.md). - -An individual user can be added as an approver for a project if they are a member of: - -- The project. -- The project's immediate parent group. -- A group that has access to the project via a [share](../members/share_project_with_groups.md). - -A group of users can also be added as approvers, though they only count as approvers if -they have direct membership to the group. In the future, group approvers may be -[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). - -If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, and users who have committed -to the merge request, do not count as eligible approvers, -if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) -and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) -are enabled on the project settings. - -When an eligible approver comments on a merge request, it displays in the -**Commented by** column of the Approvals widget. It indicates who participated in -the merge request review. Authors and reviewers can also identify who they should reach out -to if they have any questions about the content of the merge request. - -##### Implicit Approvers - -If the number of required approvals is greater than the number of assigned approvers, -approvals from other users counts towards meeting the requirement. These would be -users with developer [permissions](../../permissions.md) or higher in the project who -were not explicitly listed in the approval rules. - -##### Code Owners as eligible approvers - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. -> - Moved to GitLab Premium in 13.9. - -If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files become eligible approvers, together with members with Developer -or higher [permissions](../../permissions.md). - -To enable this merge request approval rule: - -1. Navigate to your project's **Settings > General** and expand - **Merge request (MR) approvals**. -1. Locate **Any eligible user** and choose the number of approvals required. - - - -Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab accepts approvals from -users with Developer or higher permissions, as well as by Code Owners, -indistinguishably. - -Alternatively, you can **require** -[Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** - -#### Merge Request approval segregation of duties - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. -> - Moved to Premium in 13.9. - -Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) -to a project sometimes need to be required approvers of a merge request, -before a merge to a protected branch begins. These approvers aren't allowed -to push or merge code to any branches. - -To enable this access: - -1. [Create a new group](../../group/index.md#create-a-group), and then - [add the user to the group](../../group/index.md#add-users-to-a-group), - ensuring you select the Reporter role for the user. -1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), - based on the Reporter role. -1. Navigate to your project's **Settings > General**, and in the - **Merge request (MR) approvals** section, click **Expand**. -1. Select **Add approval rule** or **Update approval rule**. -1. [Add the group](../../group/index.md#create-a-group) to the permission list. - - - -#### Adding / editing a default approval rule - -To add or edit the default merge request approval rule: - -1. Navigate to your project's **Settings > General** and expand **Merge request (MR) approvals**. - -1. Click **Add approval rule**, or **Edit**. - - Add or change the **Rule name**. - - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) - merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers are suggested based on the previous authors of - the files being changed by the merge request. - - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from - the rule. -1. Click **Add approval rule** or **Update approval rule**. - -When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules are not applied to existing merge -requests, except for changes to the [target branch](#scoped-to-protected-branch) of -the rule. - -When approval rule overrides are not allowed, all changes to these default rules -are applied to existing merge requests. Any approval rules that had previously been -manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, are not modified. - -NOTE: -If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules are taken from the target (upstream) project, not the -source (fork). - -##### Editing / overriding approval rules per merge request - -> Introduced in GitLab Enterprise Edition 9.4. - -By default, the merge request approval rule listed in each merge request (MR) can be -edited by the MR author or a user with sufficient [permissions](../../permissions.md). -This ability can be disabled in the [merge request approvals settings](#prevent-overriding-default-approvals). - -One possible scenario would be to add more approvers than were defined in the default -settings. - -When creating or editing a merge request, find the **Approval rules** section, then follow -the same steps as [Adding / editing a default approval rule](#adding--editing-a-default-approval-rule). - -#### Set up an optional approval rule - -MR approvals can be configured to be optional, which can help if you're working -on a team where approvals are appreciated, but not required. - -To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. - -You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. - -#### Multiple approval rules **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. - -In GitLab Premium, it is possible to have multiple approval rules per merge request, -as well as multiple default approval rules per project. - -Adding or editing multiple default rules is identical to -[adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button is available to add more rules, even after -a rule is already defined. - -Similarly, editing or overriding multiple approval rules per merge request is identical -to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button is available to add more rules, even after -a rule is already defined. - -When an [eligible approver](#eligible-approvers) approves a merge request, it -reduces the number of approvals left for all rules that the approver belongs to. - - - -#### Scoped to protected branch **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. - -Approval rules are often only relevant to specific branches, like `master`. -When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) -these can be scoped to all the protected branches at once by navigating to your project's -**Settings**, expanding **Merge request (MR) approvals**, and selecting **Any branch** from -the **Target branch** dropdown. - -Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - - - -To enable this configuration, see [Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). - -### Adding or removing an approval - -When an [eligible approver](#eligible-approvers) visits an open merge request, -one of the following is possible: - -- If the required number of approvals has _not_ been yet met, they can approve - it by clicking the displayed **Approve** button. - -  - -- If the required number of approvals has already been met, they can still - approve it by clicking the displayed **Approve additionally** button. - -  - -- **They have already approved this merge request**: They can remove their approval. - -  - -When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to default approval rules will **not** be applied to existing -merge requests, except for changes to the [target branch](#scoped-to-protected-branch) -of the rule. - -NOTE: -The merge request author is not allowed to approve their own merge request if -[**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) -is enabled in the project settings. - -After the approval rules have been met, the merge request can be merged if there is nothing -else blocking it. Note that the merge request could still be blocked by other conditions, -such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), -or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). - -### Approval settings - -The settings for Merge Request Approvals are found by going to -**Settings > General** and expanding **Merge request (MR) approvals**. - -#### Prevent overriding default approvals - -Regardless of the approval rules you choose for your project, users can edit them in every merge -request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). -To prevent that from happening: - -1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox. -1. Click **Save changes**. - -#### Resetting approvals on push - -You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals persist -even if there are changes added to the merge request. To enable this feature: - -1. Check the **Require new approvals when new commits are added to an MR.** - checkbox. -1. Click **Save changes**. - -NOTE: -Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals are reset if the target branch is changed. - -#### Allowing merge request authors to approve their own merge requests **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. -> - Moved to GitLab Premium in 13.9. - -By default, projects are configured to prevent merge requests from being approved by -their own authors. To change this setting: - -1. Go to your project's **Settings > General**, expand **Merge request (MR) approvals**. -1. Uncheck the **Prevent MR approval by the author.** checkbox. -1. Click **Save changes**. - -Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). - -You can prevent authors from approving their own merge requests -[at the instance level](../../admin_area/merge_requests_approvals.md). When enabled, -this setting is disabled on the project level, and not editable. - -#### Prevent approval of merge requests by their committers **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. -> - Moved to GitLab Premium in 13.9. - -You can prevent users who have committed to a merge request from approving it, -though code authors can still approve. You can enable this feature -[at the instance level](../../admin_area/merge_requests_approvals.md), which -disables changes to this feature at the project level. If you prefer to manage -this feature at the project level, you can: - -1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. - If this check box is disabled, this feature has been disabled - [at the instance level](../../admin_area/merge_requests_approvals.md). -1. Click **Save changes**. - -Read the official Git documentation for an explanation of the -[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). - -#### Require authentication when approving a merge request - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. -> - Moved to GitLab Premium in 13.9. - -NOTE: -To require authentication when approving a merge request, you must enable -**Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin Area. - -You can force the approver to enter a password in order to authenticate before adding -the approval. This enables an Electronic Signature for approvals such as the one defined -by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). -To enable this feature: - -1. Check the **Require user password for approvals.** checkbox. -1. Click **Save changes**. - -### Security approvals in merge requests **(ULTIMATE)** - -Merge Request Approvals can be configured to require approval from a member -of your security team when a vulnerability would be introduced by a merge request. - -For more information, see -[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests). - -<!-- ## 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. --> +<!-- This redirect file can be deleted after <2021-07-27>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index fc5cc4d958b..4534ce194bf 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge Request dependencies **(PREMIUM)** +# Merge request dependencies **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge Requests dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. Merge request dependencies allows a required order of merging 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 58f2c310375..b1da336aae9 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -67,7 +67,7 @@ You should be careful to configure CI/CD so that pipelines run for every merge r ### Limitations 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/README.md#onlyexcept-advanced) +is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#only--except) or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines. You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index aba75403a2a..0475996cb9b 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,452 +1,8 @@ --- -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: index, reference +redirect_to: 'reviews/index.md' --- -# Reviewing and managing merge requests **(FREE)** +This document was moved to [another location](reviews/index.md). -Merge requests are the primary method of making changes to files in a GitLab project. -Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), -which is then reviewed, and accepted (or rejected). - -## View project merge requests - -View all the merge requests in a project by navigating to **Project > Merge Requests**. - -When you access your project's merge requests, GitLab displays them in a list. -Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). - - - -## View merge requests for all projects in a group - -View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. - -You can [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists) from here. - - - -## Cached merge request count - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In a group, the sidebar displays the total count of open merge requests and this value is cached if higher -than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Enable or disable cached merge request count **(FREE SELF)** - -Cached merge request count in the left sidebar is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_merge_requests_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_merge_requests_count) -``` - -## Semi-linear history merge requests - -A merge commit is created for every merge, but the branch is only merged if -a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build also succeeds after the merge. - -Navigate to a project's settings, select the **Merge commit with semi-linear history** -option under **Merge Requests: Merge method** and save your changes. - -## View changes between file versions - -The **Changes** tab, below the main merge request details and next to the discussion tab, -shows the changes to files between branches or commits. This view of changes to a -file is also known as a **diff**. By default, the diff view compares the file in the -merge request branch and the file in the target branch. - -The diff view includes the following: - -- The file's name and path. -- The number of lines added and deleted. -- Buttons for the following options: - - Toggle comments for this file; useful for inline reviews. - - Edit the file in the merge request's branch. - - Show full file, in case you want to look at the changes in context with the rest of the file. - - View file at the current commit. - - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). -- The changed lines, with the specific changes highlighted. - - - -### Merge request diff file navigation - -When reviewing changes in the **Changes** tab the diff can be navigated using -the file tree or file list. As you scroll through large diffs with many -changes, you can quickly jump to any changed file using the file tree or file -list. - - - -### Collapsed files in the Changes view - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. - -When you review changes in the **Changes** tab, files with a large number of changes are collapsed -to improve performance. When files are collapsed, a warning appears at the top of the changes. -Click **Expand file** on any file to view the changes for that file. - -### File-by-file diff navigation - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. - -For larger merge requests, consider reviewing one file at a time. To enable this feature: - -1. In the top-right corner, select your avatar. -1. Select **Preferences**. -1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -1. Select **Save changes**. - -After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files. - - - -In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change -this behavior, you can do so from your **User preferences** (as explained above) or directly in a -merge request: - -1. Go to the merge request's **Changes** tab. -1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. -1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. - -This change overrides the choice you made in your user preferences and persists until you clear your -browser's cookies or change this behavior again. - -### Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - - - -### Incrementally expand merge request diffs - -By default, the diff shows only the parts of a file which are changed. -To view more unchanged lines above or below a change click on the -**Expand up** or **Expand down** icons. You can also click on **Show unchanged lines** -to expand the entire file. - - - -In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a -merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the -entire content by clicking **Show file contents**. - -### Ignore whitespace changes in Merge Request diff view - -If you click the **Hide whitespace changes** button, you can see the diff -without whitespace changes (if there are any). This is also working when on a -specific commit page. - - - -NOTE: -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - -## Mark files as viewed - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** - -When reviewing a merge request with many files multiple times, it may be useful to the reviewer -to focus on new changes and ignore the files that they have already reviewed and don't want to -see anymore unless they are changed again. - -To mark a file as viewed: - -1. Go to the merge request's **Diffs** tab. -1. On the right-top of the file, locate the **Viewed** checkbox. -1. Check it to mark the file as viewed. - -Once checked, the file remains marked for that reviewer unless there are newly introduced -changes to its content or the checkbox is unchecked. - -### Enable or disable file views **(FREE SELF)** - -The file view feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:local_file_reviews) -``` - -To disable it: - -```ruby -Feature.disable(:local_file_reviews) -``` - -## Perform inline code reviews - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. - -In a merge request, you can leave comments in any part of the file being changed. -In the Merge Request Diff UI, you can: - -- **Comment on a single line**: Click the **{comment}** **comment** icon in the - gutter to expand the diff lines and display a comment box. -- [**Comment on multiple lines**](#commenting-on-multiple-lines). - -### Commenting on multiple lines - -> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. - -When commenting on a diff, you can select which lines of code your comment refers -to by either: - - - -- Clicking and dragging the **{comment}** **comment** icon in the gutter to highlight - lines in the diff. GitLab expands the diff lines and displays a comment box. -- After starting a comment by clicking the **{comment}** **comment** icon in the - gutter, select the first line number your comment refers to in the **Commenting on lines** - select box. New comments default to single-line comments, unless you select - a different starting line. - -Multiline comments display the comment's line numbers above the body of the comment: - - - -## Pipeline status in merge requests widgets - -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you can see: - -- Both pre-merge and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If an application is successfully deployed to an -[environment](../../../ci/environments/index.md), the deployed environment and the link to the -Review App are both shown. - -NOTE: -When the pipeline fails in a merge request but it can still be merged, -the **Merge** button is colored red. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging -environment. - -Ongoing deployments are shown, and the state (deploying or deployed) -for environments. If it's the first time the branch is deployed, the link -returns a `404` error until done. During the deployment, the stop button is -disabled. If the pipeline fails to deploy, the deployment information is hidden. - - - -For more information, [read about pipelines](../../../ci/pipelines/index.md). - -### Merge when pipeline succeeds (MWPS) - -Set a merge request that looks ready to merge to -[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). - -### Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature branch through a merge request -on a per-branch basis. You don't need to checkout the branch, install, and preview locally. -All your changes are available to preview by anyone with the Review Apps link. - -With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../ci/review_apps/index.md). - -## Associated features - -These features are associated with merge requests: - -- [Bulk editing merge requests](../../project/bulk_editing.md): - Update the attributes of multiple merge requests simultaneously. -- [Cherry-pick changes](cherry_pick_changes.md): - Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. -- [Fast-forward merge requests](fast_forward_merge.md): - For a linear Git history and a way to accept merge requests without creating merge commits -- [Find the merge request that introduced a change](versions.md): - When viewing the commit details page, GitLab links to the merge request(s) containing that commit. -- [Merge requests versions](versions.md): - Select and compare the different versions of merge request diffs -- [Resolve conflicts](resolve_conflicts.md): - GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. -- [Revert changes](revert_changes.md): - Revert changes from any commit from a merge request. - -## Troubleshooting - -Sometimes things don't go as expected in a merge request. Here are some -troubleshooting steps. - -### Merge request cannot retrieve the pipeline status - -This can occur if Sidekiq doesn't pick up the changes fast enough. - -#### Sidekiq - -Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status should update automatically. - -#### Bug - -Merge Request pipeline statuses can't be retrieved when the following occurs: - -1. A Merge Request is created -1. The Merge Request is closed -1. Changes are made in the project -1. The Merge Request is reopened - -To enable the pipeline status to be properly retrieved, close and reopen the -Merge Request again. - -## Tips - -Here are some tips to help you be more efficient with merge requests in -the command line. - -### Copy the branch name for local checkout - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. - -The merge request sidebar contains the branch reference for the source branch -used to contribute changes for this merge request. - -To copy the branch reference into your clipboard, click the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally -via command line by running `git checkout <branch-name>`. - -### Checkout merge requests locally through the `head` ref - -A merge request contains all the history from a repository, plus the additional -commits added to the branch associated with the merge request. Here's a few -ways to checkout a merge request locally. - -You can checkout a merge request locally even if the source -project is a fork (even a private fork) of the target project. - -This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) -that is available for each merge request. It allows checking out a merge -request via its ID instead of its branch. - -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab -13.4, 14 days after a merge request gets closed or merged, the merge request -`head` ref is deleted. This means that the merge request is not available -for local checkout via the merge request `head` ref anymore. The merge request -can still be re-opened. If the merge request's branch -exists, you can still check out the branch, as it isn't affected. - -#### Checkout locally by adding a Git alias - -Add the following alias to your `~/.gitconfig`: - -```plaintext -[alias] - mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - -``` - -Now you can check out a particular merge request from any repository and any -remote. For example, to check out the merge request with ID 5 as shown in GitLab -from the `origin` remote, do: - -```shell -git mr origin 5 -``` - -This fetches the merge request into a local `mr-origin-5` branch and check -it out. - -#### Checkout locally by modifying `.git/config` for a given repository - -Locate the section for your GitLab remote in the `.git/config` file. It looks -like this: - -```plaintext -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* -``` - -You can open the file with: - -```shell -git config -e -``` - -Now add the following line to the above section: - -```plaintext -fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -In the end, it should look like this: - -```plaintext -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* - fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -Now you can fetch all the merge requests: - -```shell -git fetch origin - -... -From https://gitlab.com/gitlab-org/gitlab-foss.git - * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 - * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 -... -``` - -And to check out a particular merge request: - -```shell -git checkout origin/merge-requests/1 -``` - -All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. +<!-- This redirect file can be deleted after <2021-08-03>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..e8aa4b7c730 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..d15f5d53e55 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..3e1e9c20af9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..e27fa629672 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png Binary files differindex a31fea85be9..a31fea85be9 100644 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png +++ b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png diff --git a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png Binary files differnew file mode 100644 index 00000000000..170c04542dd --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..92d5ba5ddda --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png Binary files differindex ce1d6bab536..ce1d6bab536 100644 --- a/doc/user/project/merge_requests/img/merge_request_pipeline.png +++ b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png Binary files differnew file mode 100644 index 00000000000..6b4899bf67f --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png Binary files differnew file mode 100644 index 00000000000..ced33682459 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png Binary files differnew file mode 100644 index 00000000000..2f0be3b6d06 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_start.png b/doc/user/project/merge_requests/reviews/img/mr_review_start.png Binary files differnew file mode 100644 index 00000000000..08b4c6bb82b --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_start.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png Binary files differnew file mode 100644 index 00000000000..4bef38f7808 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png Binary files differnew file mode 100644 index 00000000000..476c50b9098 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png Binary files differnew file mode 100644 index 00000000000..80424d1f056 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png diff --git a/doc/user/project/merge_requests/img/multiline-comment-saved.png b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png Binary files differindex cceab36e62b..cceab36e62b 100644 --- a/doc/user/project/merge_requests/img/multiline-comment-saved.png +++ b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png diff --git a/doc/user/project/merge_requests/reviews/img/pending_review_comment.png b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png Binary files differnew file mode 100644 index 00000000000..70a66b3f4f0 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png Binary files differindex 625d47b1142..625d47b1142 100644 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png +++ b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..fa8331effdb --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png Binary files differnew file mode 100644 index 00000000000..58e0508d8cf --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png Binary files differnew file mode 100644 index 00000000000..927b4f812a5 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png Binary files differnew file mode 100644 index 00000000000..6f29107146d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..a4c9df0ebb9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md new file mode 100644 index 00000000000..e98a230c0de --- /dev/null +++ b/doc/user/project/merge_requests/reviews/index.md @@ -0,0 +1,417 @@ +--- +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: index, reference +--- + +# Review and manage merge requests **(FREE)** + +[Merge requests](../index.md) are the primary method of making changes to files in a +GitLab project. [Create and submit a merge request](../creating_merge_requests.md) +to propose changes. Your team makes [suggestions](suggestions.md) and leaves +[comments](../../../discussions/index.md). When your work is reviewed, your team +members can choose to accept or reject it. + +## View merge requests + +You can view merge requests for a specific project, or for all projects in a group: + +- **Specific project**: Go to your project and select **Merge requests**. +- **All projects in a group**: Go to your group and select **Merge requests**. + If your group contains subgroups, this view also displays merge requests from the subgroup projects. + GitLab displays a count of open merge requests in the left sidebar, but + [caches the value](#cached-merge-request-count) for groups with a large number of + open merge requests. + +GitLab displays open merge requests, with tabs to filter the list by open and closed status: + + + +You can [search and filter](../../../search/index.md#filtering-issue-and-merge-request-lists), +the results, or select a merge request to begin a review. + +## Bulk edit merge requests at the project level + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions + +To update multiple project merge requests at the same time: + +1. In a project, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the group level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a group, you can edit the following attributes: + +- Milestone +- Labels + +To update multiple group merge requests at the same time: + +1. In a group, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Review a merge request + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. + +When you review a merge request, you can create comments that are visible only +to you. When you're ready, you can publish them together in a single action. +To start your review: + +1. Go to the merge request you want to review, and select the **Changes** tab. + To learn more about navigating the diffs displayed in this tab, read + [Changes tab in merge requests](../changes.md). +1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +1. Write your first comment, and select **Start a review** below your comment: +  +1. Continue adding comments to lines of code, and select the appropriate button after + you write a comment: + - **Add to review**: Keep this comment private and add to the current review. + These review comments are marked **Pending** and are visible only to you. + - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. +1. (Optional) You can use [quick actions](../../quick_actions.md) inside review comments. + The comment shows the actions to perform after publication, but does not perform them + until you submit your review. +1. When your review is complete, you can [submit the review](#submit-a-review). Your comments + are now visible, and any quick actions included your comments are performed. + +### Submit a review + +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. +- When creating a review comment, select **Submit review**. +- Scroll to the bottom of the screen and select **Submit review**. + +When you submit your review, GitLab: + +- Publishes the comments in your review. +- 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. + +### Resolving/Unresolving threads + +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolvable-comments-and-threads). +When replying to a comment, a checkbox is displayed to resolve or unresolve +the thread after publication. + + + +If a particular pending comment resolves or unresolves the thread, this is shown on the pending +comment itself. + + + + + +### Adding a new comment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. + +If you have a review in progress, you will be presented with the option to **Add to review**: + + + +## Semi-linear history merge requests + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build also succeeds after the merge. + +1. Go to your project and select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Merge commit with semi-linear history**. +1. Select **Save changes**. + +## Perform inline code reviews + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. + +In a merge request, you can leave comments in any part of the file being changed. +In the merge request Diff UI, you can: + +- **Comment on a single line**: Select the **{comment}** **comment** icon in the + gutter to expand the diff lines and display a comment box. +- [**Comment on multiple lines**](#comment-on-multiple-lines). + +### Comment on multiple lines + +> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. + +When commenting on a diff, you can select which lines of code your comment refers +to by either: + + + +- Dragging the **{comment}** **comment** icon in the gutter to highlight + lines in the diff. GitLab expands the diff lines and displays a comment box. +- After starting a comment by selecting the **{comment}** **comment** icon in the + gutter, select the first line number your comment refers to in the **Commenting on lines** + select box. New comments default to single-line comments, unless you select + a different starting line. + +Multiline comments display the comment's line numbers above the body of the comment: + + + +## Pipeline status in merge requests widgets + +If you've set up [GitLab CI/CD](../../../../ci/README.md) in your project, +you can see: + +- Both pre-merge and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If an application is successfully deployed to an +[environment](../../../../ci/environments/index.md), the deployed environment and the link to the +Review App are both shown. + +NOTE: +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the [default branch](../../repository/branches/default.md) and then triggers a deployment to the staging +environment. + +Ongoing deployments are shown, and the state (deploying or deployed) +for environments. If it's the first time the branch is deployed, the link +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden. + + + +For more information, [read about pipelines](../../../../ci/pipelines/index.md). + +### Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](../merge_when_pipeline_succeeds.md). + +### Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. + +With GitLab [Route Maps](../../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../../ci/review_apps/index.md). + +## Associated features + +These features are associated with merge requests: + +- [Bulk editing merge requests](../../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](../cherry_pick_changes.md): + Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](../fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](../versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](../versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](../resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](../revert_changes.md): + Revert changes from any commit from a merge request. + +## Troubleshooting + +Sometimes things don't go as expected in a merge request. Here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur if Sidekiq doesn't pick up the changes fast enough. + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status should update automatically. + +#### Bug + +Merge request pipeline statuses can't be retrieved when the following occurs: + +1. A merge request is created +1. The merge request is closed +1. Changes are made in the project +1. The merge request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +merge request again. + +## Tips + +Here are some tips to help you be more efficient with merge requests in +the command line. + +### Copy the branch name for local checkout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. + +The merge request sidebar contains the branch reference for the source branch +used to contribute changes for this merge request. + +To copy the branch reference into your clipboard, select the **Copy branch name** button +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally +from the command line by running `git checkout <branch-name>`. + +### Checkout merge requests locally through the `head` ref + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +ways to check out a merge request locally. + +You can check out a merge request locally even if the source +project is a fork (even a private fork) of the target project. + +This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) +that is available for each merge request. It allows checking out a merge +request by using its ID instead of its branch. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab +13.4, 14 days after a merge request gets closed or merged, the merge request +`head` ref is deleted. This means that the merge request isn't available +for local checkout from the merge request `head` ref anymore. The merge request +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. + +#### Checkout locally by adding a Git alias + +Add the following alias to your `~/.gitconfig`: + +```plaintext +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `origin` remote, do: + +```shell +git mr origin 5 +``` + +This fetches the merge request into a local `mr-origin-5` branch and check +it out. + +#### Checkout locally by modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +You can open the file with: + +```shell +git config -e +``` + +Now add the following line to the above section: + +```plaintext +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +In the end, it should look like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +```shell +git fetch origin + +... +From https://gitlab.com/gitlab-org/gitlab-foss.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +And to check out a particular merge request: + +```shell +git checkout origin/merge-requests/1 +``` + +All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. + +## Cached merge request count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). + +WARNING: +This feature might not be available to you. Refer to the previous **version history** note for details. + +In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached merge request count **(FREE SELF)** + +Cached merge request count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_merge_requests_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_merge_requests_count) +``` diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md new file mode 100644 index 00000000000..0c8dd384b88 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -0,0 +1,142 @@ +--- +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: index, reference +--- + +# Suggest changes **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. + +As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request +diff threads. Then, the merge request author (or other users with appropriate +[permission](../../../permissions.md)) is able to apply these suggestions with a click, +which generates a commit in the merge request authored by the user that applied them. + +1. Choose a line of code to be changed, add a new comment, then select + the **Insert suggestion** icon in the toolbar: + +  + +1. In the comment, add your suggestion to the pre-populated code block: + +  + +1. Select either **Start a review** or **Add to review** to add your comment to a + [review](index.md), or **Add comment now** to add the comment to the thread immediately. + + The suggestion in the comment can be applied by the merge request author + directly from the merge request: + +  + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, + you can opt to add a custom commit message to describe your change. If you don't + specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions). + +  + +After the author applies a suggestion, it's marked with the **Applied** label, +the thread is automatically resolved, and GitLab creates a new commit +and pushes the suggested change directly into the codebase in the merge request's +branch. [Developer permission](../../../permissions.md) is required to do so. + +## Multi-line suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. + +Reviewers can also suggest changes to multiple lines with a single suggestion +within merge request diff threads by adjusting the range offsets. The +offsets are relative to the position of the diff thread, and specify the +range to be replaced by the suggestion when it is applied. + + + +In the previous example, the suggestion covers three lines above and four lines +below the commented line. When applied, it would replace from 3 lines _above_ +to 4 lines _below_ the commented line, with the suggested change. + + + +NOTE: +Suggestions for multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line. This allows for up to 200 changed lines per +suggestion. + +## Code block nested in suggestions + +If you need to make a suggestion that involves a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks +instead of the usual three. + + + + + +## Configure the commit message for applied suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. + +GitLab uses a default commit message +when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` + +For example, consider that a user applied 3 suggestions to 2 different files, the +default commit message is: **Apply 3 suggestion(s) to 2 file(s)** + +These commit messages can be customized to follow any guidelines you might have. +To do so, expand the **Merge requests** tab within your project's **General** +settings and change the **Merge suggestions** text: + + + +You can also use following variables besides static text: + +| Variable | Description | Output example | +|------------------------|-------------|----------------| +| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | +| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | +| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{project_path}` | The project path. | `my-group/my-project` | +| `%{project_name}` | The human-readable name of the project. | **My Project** | +| `%{suggestions_count}` | The number of suggestions applied.| **3** | +| `%{username}` | The username of the user applying suggestion(s). | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | + +For example, to customize the commit message to output +**Addresses user_1's review**, set the custom text to +`Addresses %{username}'s review`. + +NOTE: +Custom commit messages for each applied suggestion is +introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). + +## Batch suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. + +You can apply multiple suggestions at once to reduce the number of commits added +to your branch to address your reviewers' requests. + +1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: + +  + +1. Add as many additional suggestions to the batch as you wish: + +  + +1. To remove suggestions, select **Remove from batch**: + +  + +1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**: + +  + +WARNING: +Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 147171e8488..c25ee1a8a94 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -23,7 +23,7 @@ MR is merged. Collecting the coverage information is done via GitLab CI/CD's [artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. -GitLab will then take the coverage information in all the files and combine it +GitLab then takes the coverage information in all the files and combines it together. For the coverage analysis to work, you have to provide a properly formatted @@ -41,24 +41,24 @@ Other coverage analysis frameworks support the format out of the box, for exampl - [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.0.4/cmd.html#xml-reporting) (Python) Once configured, if you create a merge request that triggers a pipeline which collects -coverage reports, the coverage will be shown in the diff view. This includes reports -from any job in any stage in the pipeline. The coverage will be displayed for each line: +coverage reports, the coverage is shown in the diff view. This includes reports +from any job in any stage in the pipeline. The coverage displays for each line: - `covered` (green): lines which have been checked at least once by tests - `no test coverage` (orange): lines which are loaded but never executed - no coverage information: lines which are non-instrumented or not loaded -Hovering over the coverage bar will provide further information, such as the number +Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. NOTE: A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds -100 nodes, there can be mismatches or no matches in the Merge Request diff view. +100 nodes, there can be mismatches or no matches in the merge request diff view. ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used -to draw the visualization on the Merge Request expires **one week** after creation. +to draw the visualization on the merge request expires **one week** after creation. ### Automatic class path correction @@ -69,8 +69,8 @@ For the coverage report to properly match the files displayed on a merge request must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated Cobertura XML has the `filename` path relative to the class package directory instead. -To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser will attempt to build the -full path by doing following: +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser attempts to build the +full path by doing the following: 1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. 1. Check if the candidate path exists in the project. @@ -82,6 +82,14 @@ to the project root: ```shell Auth/User.cs Lib/Utils/User.cs +src/main/java +``` + +In the Cobertura XML, the `filename` attribute in the `class` element assumes the value is a +relative path to project's root. + +```xml +<class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> ``` And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: @@ -93,16 +101,16 @@ And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR </sources> ``` -The parser will extract `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to +The parser extracts `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to the project root, combining these extracted sources and the class filename. -If for example there is a `class` element with the `filename` value of `User.cs`, the parser will take the first candidate path -that matches which is `Auth/User.cs`. +If for example there is a `class` element with the `filename` value of `User.cs`, the parser takes the first candidate path +that matches, which is `Auth/User.cs`. -For each `class` element, the parser will attempt to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. +For each `class` element, the parser attempts to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. NOTE: -The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser will assume that +The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser assumes that the `filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations @@ -153,7 +161,7 @@ coverage-jdk11: stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: - # convert report from jacoco to cobertura + # convert report from jacoco to cobertura, use relative project path - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' # read the <source></source> tag and prepend the path to every filename attribute - 'python /opt/source2filename.py target/site/cobertura.xml' @@ -193,7 +201,7 @@ coverage-jdk11: stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: - # convert report from jacoco to cobertura + # convert report from jacoco to cobertura, use relative project path - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' # read the <source></source> tag and prepend the path to every filename attribute - 'python /opt/source2filename.py build/cobertura.xml' diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 2c77957c98d..676af4b2881 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -49,11 +49,11 @@ This only applies to commits that are in the most recent version of a merge request - if commits were in a merge request, then rebased out of that merge request, they aren't linked. -## `HEAD` comparison mode for Merge Requests +## `HEAD` comparison mode for merge requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. -Merge Requests, particularly the **Changes** tab, is where source code +Merge requests, particularly the **Changes** tab, is where source code is reviewed and discussed. In circumstances where the target branch was merged into the source branch of the merge request, the changes in the source and target branch can be shown mixed together making it hard to diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png Binary files differindex a865221c5d7..ffe1328b7d3 100644 --- a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png +++ b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png diff --git a/doc/user/project/milestones/img/milestones_project_milestone_page.png b/doc/user/project/milestones/img/milestones_project_milestone_page.png Binary files differdeleted file mode 100644 index 1faaf0b3979..00000000000 --- a/doc/user/project/milestones/img/milestones_project_milestone_page.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestones_project_milestone_page_sidebar_v13_11.png b/doc/user/project/milestones/img/milestones_project_milestone_page_sidebar_v13_11.png Binary files differnew file mode 100644 index 00000000000..3bdec8e219a --- /dev/null +++ b/doc/user/project/milestones/img/milestones_project_milestone_page_sidebar_v13_11.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index fe34dca4959..2399774c96d 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -38,7 +38,7 @@ You can assign **group milestones** to any issue or merge request of any project To view the group milestone list, in a group, go to **{issues}** **Issues > Milestones**. You can also view all milestones you have access to in the dashboard milestones list. -To view both project milestones and group milestones you have access to, click **More > Milestones** +To view both project milestones and group milestones you have access to, select **More > Milestones** on the top navigation bar. For information about project and group milestones API, see: @@ -47,9 +47,9 @@ For information about project and group milestones API, see: - [Group Milestones API](../../../api/group_milestones.md) NOTE: -If you're in a group and click **Issues > Milestones**, GitLab displays group milestones +If you're in a group and select **Issues > Milestones**, GitLab displays group milestones and the milestones of projects in this group. -If you're in a project and click **Issues > Milestones**, GitLab displays only this project's milestones. +If you're in a project and select **Issues > Milestones**, GitLab displays only this project's milestones. ## Creating milestones @@ -58,23 +58,23 @@ A permission level of [Developer or higher](../../permissions.md) is required to ### New project milestone -To create a **project milestone**: +To create a project milestone: 1. In a project, go to **{issues}** **Issues > Milestones**. -1. Click **New milestone**. +1. Select **New milestone**. 1. Enter the title, an optional description, an optional start date, and an optional due date. -1. Click **New milestone**. +1. Select **New milestone**.  ### New group milestone -To create a **group milestone**: +To create a group milestone: 1. In a group, go to **{issues}** **Issues > Milestones**. -1. Click **New milestone**. +1. Select **New milestone**. 1. Enter the title, an optional description, an optional start date, and an optional due date. -1. Click **New milestone**. +1. Select **New milestone**.  @@ -86,10 +86,10 @@ A permission level of [Developer or higher](../../permissions.md) is required to To edit a milestone: 1. In a project or group, go to **{issues}** **Issues > Milestones**. -1. Click a milestone's title. -1. Click **Edit**. +1. Select a milestone's title. +1. Select **Edit**. -You can delete a milestone by clicking the **Delete** button. +You can delete a milestone by selecting the **Delete** button. ### Promoting project milestones to group milestones @@ -182,7 +182,7 @@ The milestone sidebar on the milestone view shows the following: - 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 diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 3c3de26d7dd..18acb360f5a 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -129,7 +129,7 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit -the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic), +the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#only--except), whenever a new commit is pushed to a branch used specifically for your pages. @@ -273,6 +273,10 @@ Sure. All you need to do is download the artifacts archive from the job page. Yes. GitLab Pages doesn't care whether you set your project's visibility level to private, internal or public. +### Can I create a personal or a group website + +Yes. See the documentation about [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md). + ### Do I need to create a user/group website before creating a project website? No, you don't. You can create your project first and access it under @@ -297,3 +301,27 @@ Files listed under the public directory can be accessed through the Pages URL fo A 404 can also be related to incorrect permissions. If [Pages Access Control](pages_access_control.md) is enabled, and a user navigates to the Pages URL and receives a 404 response, it is possible that the user does not have permission to view the site. To fix this, verify that the user is a member of the project. + +For Geo instances, 404 errors on Pages occur after promoting a secondary to a primary. +Find more details in the [Pages administration documentation](../../../administration/pages/index.md#404-error-after-promoting-a-geo-secondary-to-a-primary-node) + +### Cannot play media content on Safari + +Safari requires the web server to support the [Range request header](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/CreatingVideoforSafarioniPhone/CreatingVideoforSafarioniPhone.html#//apple_ref/doc/uid/TP40006514-SW6) +in order to play your media content. For GitLab Pages to serve +HTTP Range requests, you should use the following two variables in your `.gitlab-ci.yaml` file: + +```yaml +pages: + stage: deploy + variables: + FF_USE_FASTZIP: "true" + ARTIFACT_COMPRESSION_LEVEL: "fastest" + script: + - echo "Deploying pages" + artifacts: + paths: + - public +``` + +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/README.md#artifact-and-cache-settings). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index c66f9038ed2..673a756f18d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -7,46 +7,45 @@ type: reference, howto # Protected branches **(FREE)** -[Permissions](../permissions.md) in GitLab are fundamentally defined around the +In GitLab, [permissions](../permissions.md) are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose further restrictions on certain branches, they can be protected. -## Overview +The default branch for your repository is protected by default. -By default, a protected branch does these things: +## Who can access a protected branch -- It prevents its creation, if not already created, from everybody except users - with Maintainer permission. -- It prevents pushes from everybody except users with **Allowed** permission. -- It prevents **anyone** from force pushing to the branch. -- It prevents **anyone** from deleting the branch. +When a branch is protected, the default behavior enforces +these restrictions on the branch. -**Permissions:** +| Action | Who can do it | +|--------------------------|---------------| +| Protect a branch | Maintainers only. | +| Push to the branch | GitLab administrators and anyone with **Allowed** permission. (*) | +| Force push to the branch | No one. | +| Delete the branch | No one. | -- GitLab administrators are allowed to push to the protected branches. -- Users with [Developer permissions](../permissions.md) are allowed to - create a project in a group, but might not be allowed to initially - push to the [default branch](repository/branches/default.md). +(*) Users with developer permissions can create a project in a group, +but might not be allowed to initially push to the [default branch](repository/branches/default.md). -The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +### Set the branch protection default level -See the [Changelog](#changelog) section for changes over time. +The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). -## Configuring protected branches +## Configure a protected branch -To protect a branch, you need to have at least Maintainer permission level. -The default branch for your repository is protected by default. +Prerequisite: -1. In your project, go to **Settings > Repository**. -1. Scroll to find the **Protected branches** section. -1. From the **Branch** dropdown menu, select the branch you want to protect and - click **Protect**. In the screenshot below, we chose the `develop` branch. +- You must have at least maintainer permissions. -  +To protect a branch: -1. Once done, the protected branch displays in the **Protected branches** list. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. Select **Protect**. -  +The protected branch displays in the **Protected branches** list. ## Using the Allowed to merge and Allowed to push settings @@ -141,7 +140,7 @@ all matching branches:  -## Creating a protected branch +## Create a protected branch > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. @@ -161,7 +160,7 @@ To create a new branch through the user interface: base the new branch on. Only existing protected branches and commits that are already in protected branches are accepted. -## Deleting a protected branch +## Delete a protected branch From time to time, you may need to delete or clean up protected branches. User with [Maintainer permissions](../permissions.md) and greater can manually delete protected diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 3c5cc668986..728c682b009 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -68,8 +68,8 @@ time as pushing changes: | `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [12.9](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/XXXXX) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [12.9](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/XXXXX) | +| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | If you use a push option that requires text with spaces in it, you need to enclose it in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 06ad71713d7..1ea21b1f269 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -86,7 +86,7 @@ by using a `release` node in the job definition. The release is created only if the job processes without error. If the Rails API returns an error during release creation, the release job fails. -### Schedule a future release +### Upcoming releases > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -271,10 +271,15 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m ### Release assets -You can add the following types of assets to each release: +A release contains the following types of assets: - [Source code](#source-code) -- [Links](#links) +- [Permanent links to release assets](#permanent-links-to-release-assets) + +#### Source code + +GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` +archived source code from the given Git tag. These are read-only assets. #### Permanent links to release assets @@ -285,9 +290,21 @@ GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link). -Each asset has a name, a URL of the *actual* asset location, and optionally, a -`filepath` parameter, which, if you specify it, creates a URL pointing -to the asset for the Release. The format of the URL is: +Each asset has a `name`, a `url` of the *actual* asset location, and optionally, +`filepath` and `link_type` parameters. + +A `filepath` creates a URL pointing to the asset for the Release. + +The `link_type` parameter accepts one of the following four values: + +- `runbook` +- `package` +- `image` +- `other` (default) + +This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. + +The format of the URL is: ```plaintext https://host/namespace/project/releases/:release/downloads/:filepath @@ -300,7 +317,8 @@ namespace and `gitlab-runner` project on `gitlab.com`, for example: { "name": "linux amd64", "filepath": "/binaries/gitlab-runner-linux-amd64", - "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64" + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" } ``` @@ -312,11 +330,6 @@ https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binar The physical location of the asset can change at any time and the direct link remains unchanged. -### Source code - -GitLab automatically generates `zip`, `tar.gz`, `tar.bz2` and `tar` -archived source code from the given Git tag. These are read-only assets. - ### Links A link is any URL which can point to whatever you like: documentation, built diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 1363d883e76..deacf119d38 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Default branch +# Default branch **(FREE)** When you create a new [project](../../index.md), GitLab creates a default branch in the repository. A default branch has special configuration options not shared @@ -60,7 +60,6 @@ GitLab administrators can configure a new default branch name at the > - It's deployed behind a feature flag, enabled by default. > - It cannot be enabled or disabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual @@ -75,26 +74,7 @@ Projects created on this instance after you change the setting use the custom branch name, unless a group-level or subgroup-level configuration overrides it. -#### Enable or disable custom initial branch name **(FREE SELF)** - -Setting the default initial branch name is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:global_default_branch_name) -``` - -To enable it: - -```ruby -Feature.enable(:global_default_branch_name) -``` - -### Group-level custom initial branch name **(FREE)** +### Group-level custom initial branch name > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png Binary files differdeleted file mode 100644 index fdda3858c3b..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png Binary files differnew file mode 100644 index 00000000000..a1cf9f10122 --- /dev/null +++ b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_10.png b/doc/user/project/repository/branches/img/compare_branches_v13_10.png Binary files differdeleted file mode 100644 index 2b9a5751938..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_12.png b/doc/user/project/repository/branches/img/compare_branches_v13_12.png Binary files differnew file mode 100644 index 00000000000..29627406729 --- /dev/null +++ b/doc/user/project/repository/branches/img/compare_branches_v13_12.png diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png Binary files differdeleted file mode 100644 index fdda3858c3b..00000000000 --- a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png Binary files differnew file mode 100644 index 00000000000..230abf0d875 --- /dev/null +++ b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png diff --git a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png Binary files differnew file mode 100644 index 00000000000..7eb10d10938 --- /dev/null +++ b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png diff --git a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png Binary files differnew file mode 100644 index 00000000000..f92c4279871 --- /dev/null +++ b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index f2562ef89e3..91858ff9a65 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -19,7 +19,7 @@ After pushing your changes to a new branch, you can: - [Discuss](../../../discussions/index.md) your implementation with your team - Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). -You can also request [approval](../../merge_requests/merge_request_approvals.md) +You can also request [approval](../../merge_requests/approvals/index.md) from your managers. For more information on managing branches using the GitLab UI, see: @@ -40,7 +40,7 @@ You can also manage branches using the See also: - [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation. +- [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. - [Getting started with Git](../../../../topics/git/index.md) and GitLab. ## Compare @@ -53,7 +53,7 @@ To compare branches in a repository: 1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). 1. Click **Compare** to view the changes inline: -  +  ## Delete merged branches @@ -74,7 +74,7 @@ automatically when a merge request was merged. This feature allows you to search and select a repository quickly when [comparing branches](#compare). - + Search results appear in the following order: @@ -85,7 +85,7 @@ Search results appear in the following order: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22166) in GitLab 11.5. - + This feature allows you to search and select branches quickly. Search results appear in the following order: @@ -97,6 +97,16 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi - `^feature` matches only branch names that begin with 'feature'. - `feature$` matches only branch names that end with 'feature'. +## Swap revisions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + + + +The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is clicked, the selected revisions for Source and Target will be swapped. + + + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png Binary files differdeleted file mode 100644 index f48cf176ba1..00000000000 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 70c5ef63dd4..ed5bcc1f85a 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -208,7 +208,7 @@ The repository graph displays the history of the repository network visually, in Find it under your project's **Repository > Graph**. -## Repository Languages +## Repository languages For the default branch of each repository, GitLab determines what programming languages were used and displays this on the project's pages. If this information is missing, it's @@ -226,6 +226,10 @@ detected, add the following to `.gitattributes` in the root of your repository. *.proto linguist-detectable=true ``` +Sometimes this feature can use excessive CPU. +[Read about troubleshooting this](#repository-languages-excessive-cpu-use) +and also more about customizing this feature using `.gitattributes`. + ## Locked files **(PREMIUM)** Use [File Locking](../file_lock.md) to @@ -268,7 +272,7 @@ All projects can be cloned into Visual Studio Code. To do that: When VS Code has successfully cloned your project, it opens the folder. -## Download Source Code +## Download source code > - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. > - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. @@ -310,14 +314,40 @@ When [renaming a user](../../profile/index.md#change-your-username), - The redirects are available as long as the original path is not claimed by another group, user or project. -<!-- ## Troubleshooting +## Troubleshooting + +### Repository Languages: excessive CPU use + +GitLab uses a Ruby gem to scan all the files in the repository to determine what languages are used. +[Sometimes this can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565) if +a file type needs to be parsed by the gem to determine what sort of file it is. +The gem contains a [heuristics configuration file](https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml) +that defines what file extensions need to be parsed. + +Excessive CPU use has been reported for files with the extension `.txt` and XML files with +a file extension that is not defined by the gem. + +The workaround is to specify what language to assign to specific file extensions. +The same approach should also allow misidentified file types to be fixed. + +1. Identify which language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). + The entry for `Text` files, for example: + + ```yaml + Text: + type: prose + wrap: true + aliases: + - fundamental + - plain text + extensions: + - ".txt" + ``` + +1. Add or modify `.gitattributes` in the root of your repository: -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. + ```plaintext + *.txt linguist-language=Text + ``` -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. --> + `*.txt` files have an entry in the heuristics file. The example above prevents parsing of these files. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 980c5417da6..3bbe9e6cb66 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -22,7 +22,7 @@ There are two kinds of repository mirroring supported by GitLab: When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. -Users with at least [Developer access](../../permissions.md) to the project can also force an +Users with [Maintainer access](../../permissions.md) to the project can also force an immediate update, unless: - The mirror is already being updated. @@ -65,7 +65,10 @@ For an existing project, you can set up push mirroring as follows:  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. The mirrored repository receives all changes when: +mirror diverging. + +Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. +The mirrored repository receives all changes only when: - Commits are pushed to GitLab. - A [forced update](#forcing-an-update) is initiated. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b6bde46b26a..4e8e3f1bbce 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -58,6 +58,9 @@ to display, add a file to your repository. ## Highlight lines +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.10 for GitLab SaaS instances. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11 for self-managed instances. + Web Editor enables you to highlight a single line by adding specially formatted hash information to the URL's file path segment. For example, the file path segment `MY_FILE.js#L3` instructs the Web Editor to highlight line 3. diff --git a/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png b/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png Binary files differindex 04cb011ff89..f839a391074 100644 --- a/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png +++ b/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6fa1b0aa368..f5fa6e37d1c 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -37,26 +37,34 @@ Note the following: for how you can export a project through the UI. - Imports from a newer version of GitLab are not supported. The Importing GitLab version must be greater than or equal to the Exporting GitLab version. -- Imports will fail unless the import and export GitLab instances are +- Imports fail unless the import and export GitLab instances are compatible as described in the [Version history](#version-history). -- Exports are generated in your configured `shared_path`, a temporary [shared directory](../../../development/shared_files.md) +- Exports are generated in your configured `shared_path`, a temporary shared directory, and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. - Group members are exported as project members, as long as the user has maintainer or administrator access to the group where the exported project lives. -- Project members with owner access will be imported as maintainers. +- Project members with owner access are imported as maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and - the MRs, notes, or issues will be owned by the importer. + the MRs, notes, or issues are owned by the importer. + - For project migration imports performed over GitLab.com Groups, preserving author information is + possible through a [professional services engagement](https://about.gitlab.com/services/migration/). - If an imported project contains merge requests originating from forks, - then new branches associated with such merge requests will be created + then new branches associated with such merge requests are created within a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. - Deploy keys allowed to push to protected branches are not exported. Therefore, - you will need to recreate this association by first enabling these deploy keys in your + you need to recreate this association by first enabling these deploy keys in your imported project and then updating your protected branches accordingly. ## Version history +### 14.0+ + +In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a +transitional period, you can still import any JSON exports. The new format for imports and exports +is NDJSON. + ### 13.0+ Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. @@ -95,7 +103,7 @@ Prior to 13.0 this was a defined compatibility table: Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) -and the exports between them will be compatible. +and the exports between them are compatible. ## Between CE and EE @@ -106,7 +114,7 @@ If you're exporting a project from the Enterprise Edition to the Community Editi ## Exported contents -The following items will be exported: +The following items are exported: - Project and wiki repositories - Project uploads @@ -120,7 +128,7 @@ The following items will be exported: - Push Rules - Awards -The following items will **not** be exported: +The following items are **not** exported: - Build traces and artifacts - Container registry images @@ -171,7 +179,7 @@ To export a project and its data, follow these steps:  1. Click on **Import project** to begin importing. Your newly imported project - page will appear soon. + page appears shortly. NOTE: If use of the `Internal` visibility level diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 6d37d26f6e8..d3177aa7585 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -32,38 +32,19 @@ Adjust your project's name, description, avatar, [default branch](../repository/ The project description also partially supports [standard Markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. -#### Compliance framework **(PREMIUM)** - -You can select a framework label to identify that your project has certain compliance requirements or needs additional oversight. Available labels include: - -- GDPR (General Data Protection Regulation) -- HIPAA (Health Insurance Portability and Accountability Act) -- PCI-DSS (Payment Card Industry-Data Security Standard) -- SOC 2 (Service Organization Control 2) -- SOX (Sarbanes-Oxley) - -NOTE: -Compliance framework labels do not affect your project settings. - -#### Custom compliance frameworks +#### Compliance frameworks **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. -> - [Deployed behind a feature flag](../../feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.11. -> - Enabled on GitLab.com. -> - Recommended for production use. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +You can create a framework label to identify that your project has certain compliance requirements or needs additional oversight. -GitLab 13.9 introduces custom compliance frameworks at the group-level. A group owner can create a compliance framework label -and assign it to any number of projects within that group or subgroups. When this feature is enabled, projects can only -be assigned compliance framework labels that already exist within that group. +Group owners can create, edit and delete compliance frameworks by going to **Settings** > **General** and expanding the **Compliance frameworks** section. +Compliance frameworks created can then be assigned to any number of projects via the project settings page inside the group or subgroups. -If existing [Compliance frameworks](#compliance-framework) are not sufficient, project and group owners -can now create their own. - -New compliance framework labels can be created and updated using GraphQL. +NOTE: +Attempting to create compliance frameworks on subgroups via GraphQL will cause the framework to be created on the root ancestor if the user has the correct permissions. +The web UI presents a read-only view to discourage this behavior. #### Compliance pipeline configuration **(ULTIMATE)** @@ -79,7 +60,7 @@ This feature might not be available to you. Check the **version history** note a Group owners can use the compliance pipeline configuration to define compliance requirements such as scans or tests, and enforce them in individual projects. -The [custom compliance framework](#custom-compliance-frameworks) feature allows group owners to specify the location +The [custom compliance framework](#compliance-frameworks) feature allows group owners to specify the location of a compliance pipeline configuration stored and managed in a dedicated project, distinct from a developer's project. When you set up the compliance pipeline configuration field, use the @@ -96,7 +77,9 @@ The user running the pipeline in the project should at least have Reporter acces Example `.compliance-gitlab-ci.yml` ```yaml -stages: # Allows compliance team to control the ordering and interweaving of stages/jobs +# Allows compliance team to control the ordering and interweaving of stages/jobs. +# Stages without jobs defined will remain hidden. +stages: - pre-compliance - build - test @@ -209,11 +192,12 @@ Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.md)). - Add merge request [description templates](../description_templates.md#description-templates). -- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). +- Enable [merge request approvals](../merge_requests/approvals/index.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). -- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) -- Configure [suggested changes commit messages](../../discussions/index.md#configure-the-commit-message-for-applied-suggestions) +- Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). +- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). +- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk @@ -375,6 +359,24 @@ to remove a fork relationship. ## Operations settings +### Alerts + +Configure [alert integrations](../../../operations/incident_management/integrations.md#configuration) to triage and manage critical problems in your application as [alerts](../../../operations/incident_management/alerts.md). + +### Incidents + +#### Alert integration + +Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. + +#### PagerDuty integration + +[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/incidents.md#create-incidents-via-the-pagerduty-webhook). + +#### Incident settings + +[Manage Service Level Agreements for incidents](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) with an SLA countdown timer. + ### Error Tracking Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). @@ -387,22 +389,3 @@ Add the URL of a Jaeger server to allow your users to [easily access the Jaeger [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). - -### Enable or disable custom compliance frameworks **(PREMIUM)** - -Enabling or disabling custom compliance frameworks is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:ff_custom_compliance_frameworks, Group.find(<group id>)) -``` - -To disable it: - -```ruby -Feature.disable(:ff_custom_compliance_frameworks, Group.find(<group id>)) -``` diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 78e7ded9784..df76c4682f3 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -20,13 +20,14 @@ Time Tracking allows you to: - Record the time spent working on an issue or a merge request. - Add an estimate of the amount of time needed to complete an issue or a merge request. +- View a breakdown of time spent working on an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. Data about time tracking is shown on the issue/merge request sidebar, as shown below. - + ## How to enter data @@ -56,7 +57,7 @@ To remove an estimation entirely, use `/remove_estimate`. ### Time spent -To enter time spent, write `/spend`, followed by the time. For example, if you need +To enter time spent, write `/spend`, followed by the time. For example, if you need to log 1 month, 2 weeks, 3 days, 4 hours and 5 minutes, you would write `/spend 1mo 2w 3d 4h 5m`. Time units that we support are listed at the bottom of this help page. @@ -68,13 +69,26 @@ days from the total time spent. You can't go below 0 minutes of time spent, so GitLab automatically resets the time spent if you remove a larger amount of time compared to the time that was entered already. -You can log time in the past by providing a date after the time. +You can log time in the past by providing a date after the time. For example, if you want to log 1 hour of time spent on the 31 January 2021, you would write `/spend 1h 2021-01-31`. If you supply a date in the future, the command fails and no time is logged. To remove all the time spent at once, use `/remove_time_spent`. +## View a time tracking report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271409) in GitLab 13.12. + +You can view a breakdown of time spent on an issue or merge request. + +To view a time tracking report, go to an issue or a merge request and select **Time tracking report** +in the right sidebar. + + + +The breakdown of spent time is limited to a maximum of 100 entries. + ## Configuration The following time units are available: @@ -98,4 +112,9 @@ With this option enabled, `75h` is displayed instead of `1w 4d 3h`. ## Other interesting links -- [Time Tracking landing page in the GitLab handbook](https://about.gitlab.com/solutions/time-tracking/) +- [Time Tracking solutions page](https://about.gitlab.com/solutions/time-tracking/) +- Time Tracking GraphQL references: + - [Connection](../../api/graphql/reference/index.md#timelogconnection) + - [Edge](../../api/graphql/reference/index.md#timelogedge) + - [Fields](../../api/graphql/reference/index.md#timelog) + - [Group Timelogs](../../api/graphql/reference/index.md#grouptimelogs) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index a69141ac04d..22915efef94 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -182,6 +182,8 @@ GitLab tracks wiki creation, deletion, and update events. These events are displ [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#project-activity) activity pages. +Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). + ## Customize sidebar > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 43df1cce70f..ddca0b64f81 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -41,7 +41,8 @@ For a list of words that can't be used as project names see To create a new blank project on the **New project** page: -1. On the **Blank project** tab, provide the following information: +1. Click **Create blank project** +1. Provide the following information: - The name of your project in the **Project name** field. You can't use special characters, but you can use spaces, hyphens, underscores, or even emoji. When adding the name, the **Project slug** auto populates. @@ -86,7 +87,8 @@ Built-in templates are project templates that are: To use a built-in template on the **New project** page: -1. On the **Create from template** tab, select the **Built-in** tab. +1. Click **Create from template** +1. Select the **Built-in** tab. 1. From the list of available built-in templates, click the: - **Preview** button to look at the template source itself. - **Use template** button to start creating the project. @@ -99,7 +101,8 @@ GitLab is developing Enterprise templates to help you streamline audit managemen To create a new project with an Enterprise template, on the **New project** page: -1. On the **Create from template** tab, select the **Built-in** tab. +1. Click **Create from template** +1. Select the **Built-in** tab. 1. From the list of available built-in Enterprise templates, click the: - **Preview** button to look at the template source itself. - **Use template** button to start creating the project. @@ -123,11 +126,12 @@ quickly starting projects. Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) -from the **Group** tab, under the **Create from template** tab. +from the **Group** tab, on the **Create from template** page. To use a custom project template on the **New project** page: -1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. +1. Click **Create from template** +1. Select the **Instance** tab or the **Group** tab. 1. From the list of available custom templates, click the: - **Preview** button to look at the template source itself. - **Use template** button to start creating the project. |
