diff options
Diffstat (limited to 'doc/user/project')
107 files changed, 1210 insertions, 702 deletions
diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index a5473629d4f..e14a71a7e10 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -34,7 +34,7 @@ Prerequisites: - An [Amazon Web Services](https://aws.amazon.com/) account. - Permissions to manage IAM resources. -For instance-level clusters, see [additional requirements for self-managed instances](#additional-requirements-for-self-managed-instances). **(FREE SELF)** +For instance-level clusters, see [additional requirements for self-managed instances](#additional-requirements-for-self-managed-instances). To create new Kubernetes clusters for your project, group, or instance through the certificate-based method: @@ -174,7 +174,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](../../infrastructure/clusters/connect/index.md#supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#supported-cluster-versions) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -256,7 +256,7 @@ IAM user in the Amazon AWS console, and follow these steps: #### EKS access key and ID -> Instance profiles were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) instance profiles in GitLab 13.7. If you're using GitLab 13.7 or later, you can use instance profiles to dynamically retrieve temporary credentials from AWS when needed. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index acc5ed4cb30..0c3827bcbb1 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,7 +4,7 @@ group: Configure 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 --- -# Connect existing clusters through cluster certificates **(DEPRECATED)** +# Connect existing clusters through cluster certificates (DEPRECATED) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -27,7 +27,7 @@ To add any cluster to GitLab, you need: - Either a GitLab.com account or an account for a self-managed installation running GitLab 12.5 or later. - The Maintainer role for group-level and project-level clusters. -- Access to the Admin area for instance-level clusters. **(FREE SELF)** +- Access to the Admin area for instance-level clusters. - A Kubernetes cluster. - Cluster administration access to the cluster with `kubectl`. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 19166a1ff8c..b5e2a1bad51 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,13 +1,13 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- # Kubernetes Logs (DEPRECATED) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in GitLab 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) from GitLab Ultimate to GitLab Free 12.9. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 12527853b40..a56eaa9b953 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** -> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. +> - Introduced in GitLab 10.3 +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) from GitLab Premium to GitLab Free in 13.2. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index 98ba4a1f84d..a0297a7a86f 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -6,11 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Host Security **(FREE)** -NOTE: -In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). -You can continue using Container Host Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Host Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) -instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350). +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Host Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can monitor and (optionally) block activity inside the containers themselves. This is done by leveraging 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 466bcb7916f..4e56b7e5140 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 @@ -6,6 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Getting started with Container Host Security **(FREE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Host Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + The following steps are recommended for installing Container Host Security. ## Installation steps diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index 06dc6b24620..7176a1cf1b9 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -6,11 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Network Security **(FREE)** -NOTE: -In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). -You can continue using Container Network Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Network Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) -instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) and [this GitLab Epic](https://gitlab.com/groups/gitlab-org/-/epics/7057). +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Network Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods 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 340c9397e9c..e6c91302d7b 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 @@ -6,6 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Getting started with Container Network Security **(FREE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Network Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + The following steps are recommended for installing Container Network Security. ## Installation steps diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index 1314a1948d5..473195f4c17 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -6,6 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Protecting your deployed applications **(FREE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +The Container Network Security and Container Host Security features are in their end-of-life +processes. They're +[deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). These protections are available in the Kubernetes network layer and in the container itself. At the network layer, the Container Network Security capabilities in GitLab provide basic firewall diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 265a60c6f2c..29164da307b 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3. WARNING: -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). +Serverless is currently in [alpha](../../../../policy/alpha-beta-support.md#alpha-features). ## Overview diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 4068d8e056c..eb18834cc6b 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -281,7 +281,7 @@ README.md @docs ### Approvals shown as optional -A Code Owner approval rule is optional if these conditions are not met: +A Code Owner approval rule is optional if any of these conditions are true: - The user or group are not a member of the project or parent group. - [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 2e876b24b53..57f6efa3092 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -29,7 +29,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is enabled on your repository. A good rule to follow is to provide access only to trusted users, -and make sure that the allowed users have at least the [Maintainer role](../../permissions.md) +and make sure that the allowed users have at least the Maintainer role in the GitLab project. If this security implication is a concern for your organization, diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index f57fa5aa57d..4d69209aafa 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Deploy tokens allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. -Deploy tokens can be managed by [maintainers only](../../permissions.md). +Deploy tokens can be managed only by users with the Maintainer role. Deploy tokens cannot be used with the GitLab API. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 6c17964f3a5..539f5230063 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -114,7 +114,9 @@ To re-use templates [you've created](../project/description_templates.md#create- You might also be interested in templates for various [file types in groups](../group/index.md#group-file-templates). -### Set a default template for merge requests and issues **(PREMIUM)** +### Set a default template for merge requests and issues + +> `Default.md` template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302) in GitLab 14.8. In a project, you can choose a default description template for new issues and merge requests. As a result, every time a new merge request or issue is created, it's pre-filled with the text you @@ -125,17 +127,29 @@ Prerequisites: - On your project's left sidebar, select **Settings > General** and expand **Visibility, project features, permissions**. Ensure issues or merge requests are set to either **Everyone with access** or **Only Project Members**. -To set a default description template for merge requests: +To set a default description template for merge requests, either: -1. Go to your project's **Settings**. -1. Select **Expand** under the **Merge requests** header. -1. Fill in the **Default description template for merge requests** text area. -1. Select **Save changes**. +- [Create a merge request template](#create-a-merge-request-template) named `Default.md` and save it in `.gitlab/merge_request_templates/`. + This will not overwrite the default template if one has been set in the project settings. +- Users on GitLab Premium and higher: set the default template in project settings: + + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Settings**. + 1. Expand **Merge requests**. + 1. Fill in the **Default description template for merge requests** text area. + 1. Select **Save changes**. + +To set a default description template for issues, either: -To set a default description template for issues: +- [Create an issue template](#create-an-issue-template) named `Default.md` and save it in `.gitlab/issue_templates/`. + This will not overwrite the default template if one has been set in the project settings. +- Users on GitLab Premium and higher: set the default template in project settings: -1. Select **Expand** under **Default issue template**. -1. Fill in the **Default description template for issues** text area. + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Settings**. + 1. Expand **Default issue template**. + 1. Fill in the **Default description template for issues** text area. + 1. Select **Save changes**. Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format headings, lists, and so on. @@ -143,6 +157,16 @@ headings, lists, and so on. You can also provide `issues_template` and `merge_requests_template` attributes in the [Projects REST API](../../api/projects.md) to keep your default issue and merge request templates up to date. +#### Priority of description templates + +When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues) +in various places, they have the following priorities in a project. +The ones higher up override the ones below: + +1. Template selected in project settings. +1. `Default.md` from the parent group. +1. `Default.md` from the project repository. + ## Example description template We use description templates for issues and merge requests in the diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 1d06b605aa9..9911c90863d 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -33,7 +33,7 @@ GitLab supports two different modes of file locking: ## Permissions Locks can be created by any person who has at least -[Developer role](../permissions.md) in the repository. +Developer role in the repository. Only the user who locked the file or directory can edit locked files. Other users are prevented from modifying locked files by pushing, merging, @@ -77,7 +77,7 @@ Check this document to learn more about [using Git LFS](../../topics/git/lfs/ind ### Configure Exclusive File Locks -You need the [Maintainer role](../permissions.md) to configure +You need the Maintainer role Exclusive File Locks for your project through the command line. The first thing to do before using File Locking is to tell Git LFS which @@ -226,4 +226,4 @@ To view and remove file locks: This list shows all the files locked either through LFS or GitLab UI. Locks can be removed by their author, or any user -with at least the [Maintainer role](../permissions.md). +with at least the Maintainer role. diff --git a/doc/user/project/img/time_tracking_example_v12_2.png b/doc/user/project/img/time_tracking_example_v12_2.png Binary files differdeleted file mode 100644 index 31d8c490ed1..00000000000 --- a/doc/user/project/img/time_tracking_example_v12_2.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 0c50fc77e33..62495872659 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -42,7 +42,7 @@ When issues/pull requests are being imported, the Bitbucket importer tries to fi the Bitbucket author/assignee in the GitLab database using the Bitbucket `nickname`. For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket -`username.`. If the user is not found in the GitLab database, the project creator +`username`. If the user is not found in the GitLab database, 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 Bitbucket author is kept. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index da47b673c29..4e3642eb3bd 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -5,130 +5,110 @@ 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 --- -# Import your project from Bitbucket Server to GitLab **(FREE)** +# Import your project from Bitbucket Server **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. NOTE: -The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org). -Use the [Bitbucket Cloud importer](bitbucket.md) for that. +This process is different than [importing from Bitbucket Cloud](bitbucket.md). -Import your projects from Bitbucket Server to GitLab with minimal effort. +From Bitbucket Server, you can import: -The Bitbucket importer can import: - -- Repository description (GitLab 11.2+) -- Git repository data (GitLab 11.2+) -- Pull requests (GitLab 11.2+) -- Pull request comments (GitLab 11.2+) +- Repository description +- Git repository data +- Pull requests +- Pull request comments When importing, repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Limitations +## Import your Bitbucket repositories -- 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. -- Pull request approvals are not imported. -- 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). +Prerequisites: -## How it works +- An administrator must have enabled the **Bitbucket Server** in + **Admin > Settings > General > Visibility and access controls > Import sources**. +- Review the importer's [limitations](#limitations). -The Bitbucket Server importer works as follows: +To import your Bitbucket repositories: -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 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. +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **Bitbucket Server**. +1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. +1. Select the projects to import, or import all projects. You can filter projects by name and select + the namespace for which to import each project. -### User assignment +## Limitations -When issues/pull requests are being imported, the Bitbucket importer tries to -find the author's email address with a confirmed email address in the GitLab -user database. If no such user is available, the project creator is set as -the author. The importer appends a note in the comment to mark the original -creator. +- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are + inserted as comments in the merge request. +- Bitbucket Server allows multiple threading levels. The importer collapses this into one thread and + quotes part of the original comment. +- Declined pull requests have unreachable commits. This prevents the importer from generating a + proper diff. These pull requests show up as empty changes. +- Project filtering doesn't support fuzzy search. Only starts with or full match strings are + supported. -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. +The following aren't imported: -#### User assignment by username +- Pull request approvals +- Attachments in Markdown +- Task lists +- Emoji reactions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4. -> - 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. +## User assignment -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +When issues and pull requests are importing, the importer tries to find the author's email address +with a confirmed email address in the GitLab user database. If no such user is available, the +project creator is set as the author. The importer appends a note in the comment to mark the +original creator. -If you've enabled this feature, the importer tries to find a user in the GitLab user database with -the author's: +The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the +repository imports under the namespace of the user who started the import process. -- `username` -- `slug` -- `displayName` +### User assignment by username -If the user is not found by any of these properties, the project creator is set as the author. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default. +> - Not recommended for production use. -##### Enable or disable User assignment by username +FLAG: +On self-managed GitLab and GitLab.com, by default this feature is not available. To make it +available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +named `bitbucket_server_user_mapping_by_username`. This feature is not ready for production use. -User assignment by username 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. +With this feature enabled, the importer tries to find a user in the GitLab user database with the +author's: -To enable it: +- `username` +- `slug` +- `displayName` -```ruby -Feature.enable(:bitbucket_server_user_mapping_by_username) -``` +If no user matches these properties, the project creator is set as the author. -To disable it: +## Troubleshooting -```ruby -Feature.disable(:bitbucket_server_user_mapping_by_username) -``` +### General -## Import your Bitbucket repositories +If the GUI-based import tool does not work, you can try to: -Prerequisite: +- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) + Bitbucket Server endpoint. +- Set up [repository mirroring](../repository/mirror/index.md). + It provides verbose error output. -- An administrator must have enabled the importer in - **Admin > Application Settings > Visibility and access controls > Import sources**. +See the [troubleshooting section](bitbucket.md#troubleshooting) +for Bitbucket Cloud. -To import your Bitbucket repositories: +### LFS objects not imported -1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. -1. Select **Import project**. -1. Select **Bitbucket Server**. -1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. -1. Select the projects that you'd like to import or import all projects. - You can filter projects by name and select the namespace - each project will be imported for. +If the project import completes but LFS objects can't be downloaded or cloned, you may be using a +password or personal access token containing special characters. For more information, see +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). -## Automate group and project import **(PREMIUM)** +## Related topics For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). - -## Troubleshooting - -If the GUI-based import tool does not work, you can try to: - -- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint. -- Set up [Repository Mirroring](../repository/mirror/index.md), which provides verbose error output. - -See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index d4cca723333..9f1c049045c 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,7 +26,7 @@ The following aspects of a project are imported: - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) - Pull request comments replies in discussions ([GitLab.com & 14.5+](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)) -- Diff Notes suggestions ([GitLab.com & 14.7+](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)) [with a flag](../../../administration/feature_flags.md) named `github_importer_use_diff_note_with_suggestions`. Enabled by default. +- Diff Notes suggestions ([GitLab.com & 14.7+](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)) References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -181,8 +181,7 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances -NOTE: -An administrator role on the GitLab server is required for this process. +Administrator access on the GitLab server is required for this process. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 001f0d56cc5..41ef15108ec 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -50,7 +50,7 @@ information, see the prerequisites and important notes in these sections: NOTE: 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 -the Administrator role. +administrator access. To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). Migrate the assets in this order: diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index c6992422733..5f7475eac36 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -40,9 +40,8 @@ iterations of the GitLab Jira importer. ### Permissions -In order to be able to import issues from a Jira project you need to have read access on Jira -issues and a [Maintainer or higher](../../permissions.md#project-members-permissions) role in the -GitLab project that you wish to import into. +To be able to import issues from a Jira project you must have read access on Jira +issues and at least the Maintainer role in the GitLab project that you wish to import into. ### Jira integration diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 80f2d6d7e62..96b38b49960 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The Phabricator task importer is in -[beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and is +[beta](../../../policy/alpha-beta-support.md#beta-features) and is [**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports only an issue's title and description. The GitLab project created during the import process contains only issues, and the associated repository is disabled. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index bee097cdcbe..801c2520bda 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -105,7 +105,6 @@ Projects include the following [features](https://about.gitlab.com/features/): - [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): View project dependencies. **(ULTIMATE)** - [Requirements](requirements/index.md): Create criteria to check your products against. **(ULTIMATE)** -- [Static Site Editor](static_site_editor/index.md): Edit content on static websites without prior knowledge of the codebase or Git commands. - [Code Intelligence](code_intelligence.md): Navigate code. ## Project integrations diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 38de8d9f1af..bf343078634 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -46,6 +46,7 @@ integration in GitLab. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. 1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification). 1. Enter the [build key](#identify-the-bamboo-build-plan-build-key) from your Bamboo build plan. 1. If necessary, enter a username and password for a Bamboo user that has diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index ac6e18e8e6a..9764c4d44a0 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least -the [Maintainer role](../../permissions.md) on the project. +the Maintainer role on the project. ## Integrations diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 1ff558b569b..b317e65bdf2 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -67,7 +67,7 @@ After you enable custom slash commands in Mattermost, you need configuration information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to - GitLab as a user with [Administrator role](../../permissions.md). + GitLab as a user with administrator access. 1. On the top bar, select **Menu > Admin**. 1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 5b83df9b22e..8ecc16050be 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -82,6 +82,15 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). +## SSL verification + +By default, the SSL certificate for outgoing HTTP requests is verified based on +an internal list of Certificate Authorities. This means the certificate cannot +be self-signed. + +You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook) +and some integrations. + ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. Learn more about [troubleshooting service hooks](webhooks.md#troubleshoot-webhooks). diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index de7ac6782d6..760b5030416 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index a07abf26fba..e8d611af30d 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 97f69d65412..76d13d5487c 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index a5fc398e558..9bdd4945f5d 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 26d006adeb9..33a06958e0c 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index ad89543e9a6..ecf75d7b17a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 03bf9258659..e123000e0c5 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 89c174f8fb9..fda7744e847 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index de152aabde5..dd4cdb632e6 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -13,7 +13,7 @@ You can configure GitLab to send notifications to a Webex Teams space: ## Create a webhook for the space -1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054-23307). 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. Select **ADD**. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index ab70a2d43f4..9d8b98edba1 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -773,6 +773,7 @@ Merge request events are triggered when: - A new merge request is created. - An existing merge request is updated, approved, unapproved, merged, or closed. - A commit is added in the source branch. +- All threads are resolved on the merge request. The available values for `object_attributes.action` in the payload are: @@ -838,6 +839,7 @@ Payload example: "updated_at": "2013-12-03T17:23:34Z", "milestone_id": null, "state": "opened", + "blocking_discussions_resolved": true, "merge_status": "unchecked", "target_project_id": 14, "iid": 1, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 8bc2b51276a..ace5783c852 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -57,7 +57,7 @@ You can configure a webhook for a group or a project. The URL must be percent-encoded if it contains one or more special characters. 1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. 1. In the **Trigger** section, select the [events](webhook_events.md) to trigger the webhook. -1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](#verify-an-ssl-certificate). +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification). 1. Select **Add webhook**. ## Test a webhook @@ -123,15 +123,6 @@ The token is sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check the token to verify that the request is legitimate. -## Verify an SSL certificate - -By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities. This means the certificate cannot -be self-signed. - -You can turn off SSL verification in the [webhook settings](#configure-a-webhook) -in your GitLab projects. - ## Filter push events by branch Push events can be filtered by branch using a branch name or wildcard pattern diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 47a2d215024..71440298d85 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -194,7 +194,7 @@ card includes: ## Permissions -Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the +Users with at least the Reporter role can use all the functionality of the issue board feature to create or delete lists. They can also drag issues from one list to another. ## Ordering issues in a list @@ -402,7 +402,7 @@ To set a WIP limit for a list: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. > - [View blocking issues when hovering over blocked icon](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10. -If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked +If an issue is [blocked by another issue](issues/related_issues.md#blocking-issues), an icon appears next to its title to indicate its blocked status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. @@ -496,6 +496,9 @@ The steps depend on the scope of the list: ### Filter issues +> - Filtering by iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. +> - Filtering by issue type [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268152) in GitLab 14.6. + You can use the filters on top of your issue board to show only the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). @@ -504,11 +507,12 @@ You can filter by the following: - Assignee - Author - Epic -- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) +- Iteration - Label - Milestone - My Reaction - Release +- Type (issue/incident) - Weight #### Filtering issues in a group board @@ -565,7 +569,7 @@ You can move issues and lists by dragging them. Prerequisites: -- You must have at least the Reporter [role](../permissions.md#project-members-permissions) for a project in GitLab. +- You must have at least the Reporter role for a project in GitLab. To move an issue, select the issue card and drag it to another position in its current list or into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index aba8c45699c..41de91d9bd7 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -25,7 +25,7 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid /zoom https://zoom.us/j/123456789 ``` -If the Zoom meeting URL is valid and you have at least the Reporter [role](../../permissions.md), +If the Zoom meeting URL is valid and you have at least the Reporter role, a system alert notifies you of its successful addition. The issue's description is automatically edited to include the Zoom link, and a button appears right under the issue's title. @@ -44,5 +44,5 @@ Similarly to adding a Zoom meeting, you can remove it with a quick action: /remove_zoom ``` -If you have at least the Reporter [role](../../permissions.md), +If you have at least the Reporter role, a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index e8c58f2feb9..15130523da6 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -11,19 +11,20 @@ Confidential issues are [issues](index.md) visible only to members of a project Confidential issues can be used by open source projects and companies alike to keep security vulnerabilities private or prevent surprises from leaking out. -## Making an issue confidential +## Make an issue confidential -You can make an issue confidential during issue creation or by editing -an existing one. +You can make an issue confidential when you create or edit an issue. When you create a new issue, a checkbox right below the text area is available to mark the issue as confidential. Check that box and hit the **Create issue** button to create the issue. For existing issues, edit them, check the confidential checkbox and hit **Save changes**. +When you create a confidential issue in a project, the project becomes listed in the **Contributed projects** section in your [profile](../../profile/index.md). **Contributed projects** does not show information about the confidential issue; it only shows the project name. + ![Creating a new confidential issue](img/confidential_issues_create.png) -## Modifying issue confidentiality +## Modify issue confidentiality There are two ways to change an issue's confidentiality. @@ -42,15 +43,15 @@ system note in the issue's comments. ![Confidential issues system notes](img/confidential_issues_system_notes.png) -When an issue is made confidential, only users with at least the [Reporter role](../../permissions.md) +When an issue is made confidential, only users with at least the Reporter role for the project have access to the issue. Users with Guest or [Minimal](../../permissions.md#users-with-minimal-access) roles can't access the issue even if they were actively participating before the change. -## Indications of a confidential issue +## Confidential issue indicators There are a few things that visually separate a confidential issue from a -regular one. In the issues index page view, you can see the eye-slash (**(eye-slash)**) icon +regular one. In the issues index page view, you can see the eye-slash (**{eye-slash}**) icon next to the issues that are marked as confidential: ![Confidential issues index page](img/confidential_issues_index_page.png) @@ -74,19 +75,18 @@ There is also an indicator on the sidebar denoting confidentiality. ## Merge requests for confidential issues -Although you can make issues be confidential in public projects, you cannot make -confidential merge requests. Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) -that prevent leaks of private data. +Although you can create confidential issues (and make existing issues confidential) in a public project, you cannot make confidential merge requests. +Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) that prevent leaks of private data. ## Permissions and access to confidential issues There are two kinds of level access for confidential issues. The general rule is that confidential issues are visible only to members of a project with at -least the Reporter [role](../../permissions.md#project-members-permissions). However, a guest user can also create +least the Reporter role. However, a guest user can also create confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with the [Maintainer role](../../permissions.md) and the Guest role +For example, here's what a user with the Maintainer role and the Guest role sees in the project's search results respectively. | Maintainer role | Guest role | diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index a9fca4f2b75..947fbdcc2d1 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -61,29 +61,29 @@ fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: -| Column | Description | -|-------------------|-------------| -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| Title | Issue `title` | -| State | `Open` or `Closed` | -| Description | Issue `description` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | -| Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | -| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Column | Description | +|------------------------------------------|-----------------------------------------------------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | +| Assignee Username | Username of the author, with the `@` symbol omitted | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| [Epic](../../group/epics/index.md) ID | ID of the parent epic, introduced in 12.7 | +| [Epic](../../group/epics/index.md) Title | Title of the parent epic, introduced in 12.7 | ## Limitations diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 69dc0cbafd8..e4b8efd27ed 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -14,9 +14,7 @@ retain columns such as labels and milestones, consider the [Move Issue feature]( The user uploading the CSV file is set as the author of the imported issues. -NOTE: -A permission level of [Developer](../../permissions.md), or higher, is required -to import issues. +You must have at least the Developer role for a project to import issues. ## Prepare for the import diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index ecf35fc4dcf..e7bb5ad4eeb 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Design Management **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab Premium 12.2. -> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab Premium 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. +> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. Design Management allows you to upload design assets (including wireframes and mockups) to GitLab issues and keep them stored in a single place, accessed by the Design @@ -84,10 +84,10 @@ You can find to the **Design Management** section in the issue description: ## Adding designs -> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.9. -> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.9. +> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. +> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. > - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. To upload Design images, drag files from your computer and drop them in the Design Management section, or select **click to upload** to select images from your file browser: @@ -142,9 +142,9 @@ to help summarize changes between versions. ### Exploring designs by zooming -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab Premium 12.7. -> - Drag to move a zoomed image [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. +> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. Designs can be explored in greater detail by zooming in and out of the image. Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. @@ -155,8 +155,8 @@ While zoomed in, you can drag the image to move around it. ## Deleting designs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab Premium 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. There are two ways to delete designs: manually delete them individually, or select a few of them to delete at once, @@ -190,8 +190,8 @@ You can change the order of designs by dragging them to a new position. ## Starting discussions on designs -> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) adjusting a pin's position in GitLab 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. When a design is uploaded, you can start a discussion by selecting the image on the exact location you would like the discussion to be focused on. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 2c20ccdcee0..2630052d806 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Due dates **(FREE)** Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are -shipped on time. Users need at least the Reporter [role](../../permissions.md) +shipped on time. Users need at least the Reporter role to be able to edit the due date. All users with permission to view the issue can view the due date. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 8f17f399cb0..756fe9699f1 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -15,10 +15,8 @@ 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.) -You can remove weight from an issue -as well. +value from 0, 1, 2, and so on. +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 weight icon (**{weight}**). diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index d120df82dbf..155d6260a5c 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -29,7 +29,7 @@ You can create an issue in many ways in GitLab: Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To create an issue: @@ -52,7 +52,7 @@ to the projects in the group. Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project in the group. +- You must have at least the Guest role for the project in the group. To create an issue from a group: @@ -78,7 +78,7 @@ You can create a new issue from an existing one. The two issues can then be mark Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To create an issue from another issue: @@ -98,7 +98,7 @@ You can create a new issue from an [issue board](../issue_board.md). Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To create an issue from a project issue board: @@ -133,7 +133,7 @@ Prerequisites: - Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) configured. - There must be at least one issue in the issue list. -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To email an issue to a project: @@ -224,7 +224,7 @@ You can edit an issue's title and description. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To edit an issue: @@ -242,7 +242,7 @@ You can edit multiple issues at a time when you're in a project. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project. To edit multiple issues at the same time: @@ -275,7 +275,7 @@ You can edit multiple issues across multiple projects when you're in a group. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for a group. +- You must have at least the Reporter role for a group. To edit multiple issues at the same time: @@ -300,9 +300,11 @@ When you move an issue, it's closed and copied to the target project. The original issue is not deleted. A system note, which indicates where it came from and went to, is added to both issues. +Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. + Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project. To move an issue: @@ -317,7 +319,7 @@ You can move all open issues from one project to another. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have access to the Rails console of the GitLab instance. To do it: @@ -351,7 +353,7 @@ The issue is marked as closed but is not deleted. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To close an issue, you can do the following: @@ -364,7 +366,7 @@ To close an issue, you can do the following: Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To reopen a closed issue, at the top of the issue, select **Reopen issue**. A reopened issue is no different from any other open issue. @@ -440,7 +442,7 @@ in the [project's settings](../settings/index.md). Prerequisites: -- You must have at least the [Maintainer role](../../permissions.md) for the project. +- You must have at least the Maintainer role for the project. To disable automatic issue closing: @@ -466,7 +468,7 @@ Merge requests in other projects can still close another project's issues. Prerequisites: -- You must have the [administrator access level](../../../administration/index.md) for your GitLab instance. +- You must have [administrator access](../../../administration/index.md) to your GitLab instance. To change the default issue closing pattern, edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) @@ -476,7 +478,7 @@ of your installation. Prerequisites: -- You must be the issue author or have at least the [Reporter role](../../permissions.md) for the project. +- You must be the issue author or have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To change issue type: @@ -494,7 +496,7 @@ To change issue type: Prerequisites: -- You must have the [Owner role](../../permissions.md) for a project. +- You must have the Owner role for a project. To delete an issue: @@ -508,9 +510,9 @@ Alternatively: ## Promote an issue to an epic **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab Ultimate 11.6. -> - Moved to GitLab Premium in 12.8. -> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. +> - Moved from GitLab Ultimate to GitLab Premium in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab 13.6. You can promote an issue to an [epic](../../group/epics/index.md) in the immediate parent group. @@ -622,7 +624,7 @@ This status marks issues as progressing as planned or needing attention to keep Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project. To edit health status of an issue: diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 98e940b6b51..f957d701a3b 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Multiple Assignees for Issues **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 8a2a104c54d..f83ebc5e8a8 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Linked issues **(FREE)** -> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) from GitLab Premium to GitLab Free in 13.4. Linked issues are a bi-directional relationship between any two issues and appear in a block below -the issue description. Issues can be across groups and projects. +the issue description. You can link issues in different projects. The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. @@ -23,13 +23,18 @@ To manage linked issues through our API, visit the [issue links API documentatio > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in GitLab 13.0. > When you try to close an issue with open blockers, you see a warning that you can dismiss. -1. Link one issue to another by selecting the add linked issue button (**{plus}**) in the - **Linked issues** section of an issue. +Prerequisites: +- You must have at least the Reporter role for both projects. + +To link one issue to another: + +1. In the **Linked issues** section of an issue, + select the add linked issue button (**{plus}**). 1. Select the relationship between the two issues. Either: - **relates to** - - **blocks** **(PREMIUM)** - - **is blocked by** **(PREMIUM)** + - **[blocks](#blocking-issues)** + - **[is blocked by](#blocking-issues)** 1. Input the issue number or paste in the full URL of the issue. ![Adding a related issue](img/related_issues_add_v12_8.png) @@ -64,3 +69,10 @@ Due to the bi-directional relationship, the relationship no longer appears in ei ![Removing a related issue](img/related_issues_remove_v12_8.png) Access our [permissions](../../permissions.md) page for more information. + +## Blocking issues **(PREMIUM)** + +When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or +**is blocked by** another issue. + +Issues that block other issues have an icon (**{issue-block}**) shown in the issue lists and [boards](../issue_board.md). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 0340f15c25c..329f65bfacd 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -27,7 +27,7 @@ The available sorting options can change based on the context of the list. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. When you sort by **Blocking**, the issue list changes to sort descending by the -number of issues each issue is blocking. +number of issues each issue is [blocking](related_issues.md#blocking-issues). ## Sorting by created date diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 2dc29f5d725..8be2ade3f2f 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -12,20 +12,30 @@ Each member gets a role, which determines what they can do in the project. ## Add users to a project +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default the modal window feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) +named `invite_members_group_modal`. +On GitLab.com, this feature is available. + Add users to a project so they become members and have permission to perform actions. Prerequisite: -- You must have the [Maintainer or Owner role](../../permissions.md). +- You must have the Maintainer or Owner role. To add a user to a project: -1. Go to your project and select **Project information > Members**. -1. On the **Invite member** tab, under **GitLab member or Email address**, type the username or email address. - In GitLab 13.11 and later, you can [replace this form with a modal window](#add-a-member-modal-window). -1. Select a [role](../../permissions.md). -1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. +1. Select **Invite members**. +1. Enter an email address and select a [role](../../permissions.md). +1. Optional. Select an **Access 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. @@ -40,6 +50,15 @@ using the email address the invitation was sent to. ## Add groups to a project +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default the modal window feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) +named `invite_members_group_modal`. +On GitLab.com, this feature is available. + When you add a group to a project, each user in the group gets access to the project. Each user's access is based on: @@ -48,15 +67,16 @@ Each user's access is based on: Prerequisite: -- You must have the [Maintainer or Owner role](../../permissions.md). +- You must have the Maintainer or Owner role. To add groups to a project: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Project information > 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 a group**. +1. Select a group. +1. Select the highest [role](../../permissions.md) for users in the group. +1. Optional. Select an **Access expiration date**. On that date, the group can no longer access the project. 1. Select **Invite**. The members of the group are not displayed on the **Members** tab. @@ -72,7 +92,7 @@ retain the same permissions as the project you import them from. Prerequisite: -- You must have the [Maintainer or Owner role](../../permissions.md). +- You must have the Maintainer or Owner role. To import users: @@ -111,7 +131,7 @@ group itself. Prerequisites: -- You must have the [Owner role](../../permissions.md). +- You must have the Owner role. - Optional. Unassign the member from all issues and merge requests that are assigned to them. @@ -203,44 +223,3 @@ Prerequisite: ## Share a project with a group Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). - -### Add a member modal window - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In GitLab 13.11, you can optionally replace the form to add a member with a modal window. -To add a member after enabling this feature: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. -1. Select **Invite members**. -1. Enter an email address and select a role. -1. Optional. Select an **Access expiration date**. -1. Select **Invite**. - -### Enable or disable modal window **(FREE SELF)** - -The modal window for adding a member is under development and is 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(:invite_members_group_modal) -``` - -To disable it: - -```ruby -Feature.disable(:invite_members_group_modal) -``` diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index e67af8dc936..612f499bb65 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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, howto --- # Accessibility testing **(FREE)** diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index b10d6597c1e..5826ebcab49 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -50,7 +50,7 @@ You can push directly to the branch of the forked repository if: - The author of the merge request has enabled contributions from upstream members. -- You have at least the [Developer role](../../permissions.md) in the +- You have at least the Developer role in the upstream project. In the following example: diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index dddd3925dbb..e940426dc67 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -8,7 +8,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/appro # 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. +> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 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. While [GitLab Free](https://about.gitlab.com/pricing/) allows @@ -89,7 +89,7 @@ a merge request from merging without approval. ## Required approvals **(PREMIUM)** -> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9. +> Moved to GitLab Premium 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: @@ -103,7 +103,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple to determine who should review the work. - Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability. **(ULTIMATE)** + before merging code that could introduce a vulnerability. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 129010010e7..fa447ea35af 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -76,9 +76,9 @@ To edit a merge request approval rule: select **{remove}** **Remove**. 1. Select **Update approval rule**. -## Add multiple approval rules **(PREMIUM)** +## Add multiple approval rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 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 @@ -127,8 +127,8 @@ 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). +they have direct membership to the group. Group approvers are +restricted to only groups [with share access to the project](../../members/share_project_with_groups.md). A user's membership in an approvers group affects their individual ability to approve in these ways: @@ -143,7 +143,7 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-approvals-by-users-who-add-commits) project setting. -### Code owners as eligible approvers **(PREMIUM)** +### Code owners as eligible approvers > Moved to GitLab Premium in 13.9. @@ -158,14 +158,14 @@ become eligible approvers in the project. To enable this merge request approval You can also [require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) -for protected branches. **(PREMIUM)** +for protected branches. -## Merge request approval segregation of duties **(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 have to grant users with the Reporter [role](../../../permissions.md#project-members-permissions) +You may have to grant users with the Reporter role 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 @@ -202,7 +202,7 @@ on a merge request, you can either add or remove approvers: Administrators can change the [merge request approvals settings](settings.md#prevent-editing-approval-rules-in-merge-requests) to prevent users from overriding approval rules for merge requests. -## Configure optional approval rules **(PREMIUM)** +## 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: @@ -211,9 +211,9 @@ appreciated, but not required. To make an approval rule optional: - 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)** +## Approvals for protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.8. Approval rules are often relevant only to specific branches, like your [default branch](../../repository/branches/default.md). To configure an @@ -229,3 +229,16 @@ approval rule for certain branches: ![Scoped to protected branch](img/scoped_to_protected_branch_v13_10.png) 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). + +## Troubleshooting + +### Approval rule name can't be blank + +As a workaround for this validation error, you can delete the approval rule through +the API. + +1. [GET a project-level rule](../../../../api/merge_request_approvals.md#get-a-single-project-level-rule). +1. [DELETE the rule](../../../../api/merge_request_approvals.md#delete-project-level-rule). + +For more information about this validation error, read +[issue 285129](https://gitlab.com/gitlab-org/gitlab/-/issues/285129). diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 4ae59a76a9a..37ecc1b8d06 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -16,7 +16,7 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. -The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers +The project maintainers get the Maintainer role and the regular developers get the Developer role. Maintainers mark the authoritative branches as 'Protected'. @@ -25,7 +25,7 @@ Developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. -By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a +By default, only users with the Maintainer role can merge changes into a protected branch. **Advantages** @@ -39,7 +39,7 @@ protected branch. ## Forking workflow -With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular +With the forking workflow, maintainers get the Maintainer role and regular developers get the Reporter role on the authoritative repository, which prohibits them from pushing any changes to it. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 6668e1736cf..9c7d9e2bf19 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -1,13 +1,12 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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, howto --- # Browser Performance Testing **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in GitLab 10.3. If your application offers a web interface and you're using [GitLab CI/CD](../../../ci/index.md), you can quickly determine the rendering performance diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index d348c00bdc2..8796ea0635b 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,149 +5,151 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes tab in merge requests **(FREE)** +# Changes in merge requests **(FREE)** -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. +A [merge request](index.md) proposes a set of changes to files in a branch in your repository. These +changes are shown as a _diff_ (difference) between the current state and the proposed +changes. -The diff view includes the following: +By default, the diff view compares the versions of files in the merge request source branch +to the files in the target branch, and shows only the parts of a file that have changed. -- 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. +![Example screenshot of a source code diff](img/mr-diff-example_v14_8.png) -![Example screenshot of a source code diff](img/merge_request_diff_v12_2.png) +## Show all changes in a merge request -## Merge request diff file navigation +To view the diff of changes included in a merge request: -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. +1. Go to your merge request. +1. Below the merge request title, select **Changes**. +1. If the merge request changes many files, you can jump directly to a specific file: + 1. Select **Show file browser** (**{file-tree}**) to display the file tree. + 1. Select the file you want to view. + 1. To hide the file browser, select **Show file browser** again. -![Merge request diff file navigation](img/merge_request_diff_file_navigation.png) +In [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) and later, files +with many changes are collapsed to improve performance. GitLab displays the message: +**Some changes are not shown**. To view the changes for that file, select **Expand file**. -## Collapsed files in the Changes view +## Show one file at a time -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. +> - [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. -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. +For larger merge requests, you can review one file at a time. You can change this setting +[temporarily in a merge request](#in-a-merge-request-show-only-one-file-at-a-time), or +so it [applies to all merge requests](#in-all-merge-requests-show-only-one-file-at-a-time). -## File-by-file diff navigation +### In a merge request, show only one file at a time -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) in GitLab 13.7. + +To temporarily change your viewing preferences for a specific merge request: + +1. Go to your merge request, and below the merge request title, select **Changes**. +1. Select **Preferences** (**{settings}**). +1. Select or clear the **Show one file at a time** checkbox. -For larger merge requests, consider reviewing one file at a time. To enable this feature: +This change overrides your choice in your user preferences. It persists until you +clear your browser's cookies or change this behavior again. + +### In all merge requests, show only one file at a time + +To view one file at a time for all of your merge requests: 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. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox. 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. +After you enable this setting, GitLab displays only one file at a time when you review +merge requests. To view other changed files, either: + +- Scroll to the end of the file and select either **Prev** or **Next**. +- Select **Show file browser** (**{file-tree}**) and select another file to view. + +## Compare changes inline + +You can view the changes inline: -![File-by-file diff navigation](img/file_by_file_v13_2.png) +1. Go to your merge request, and below the title, select **Changes**. +1. Select **Preferences** (**{settings}**). +1. In the **Compare changes** area, select **Inline**. -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: +The changes are displayed after the original text. -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. +![inline changes](img/changes-inline_v14_8.png) -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. +## Compare changes side-by-side -## Incrementally expand merge request diffs +Depending on the length of the changes in your merge request, you may find it +easier to view the changes inline, or side-by-side: -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. +1. Go to your merge request, and below the title, select **Changes**. +1. Select **Preferences** (**{settings}**). +1. In the **Compare changes** area, select **Side-by-side**. -![Incrementally expand merge request diffs](img/incrementally_expand_merge_request_diffs_v12_2.png) +The changes are displayed across from one another. -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**. +![side-by-side changes](img/changes-sidebyside_v14_8.png) -## Ignore whitespace changes in Merge Request diff view +## Expand or collapse comments + +When reviewing code changes, you can hide inline comments: + +1. Go to your merge request, and below the title, select **Changes**. +1. Scroll to the file that contains the comments you want to hide. +1. Scroll to the line the comment is attached to, and select **Collapse** (**{collapse}**): + ![collapse a comment](img/collapse-comment_v14_8.png) + +To expand inline comments and show them again: + +1. Go to your merge request, and below the title, select **Changes**. +1. Scroll to the file that contains the collapsed comments you want to show. +1. Scroll to the line the comment is attached to, and select the user avatar: + ![expand a comment](img/expand-comment_v14_8.png) + +## Ignore whitespace changes Whitespace changes can make it more difficult to see the substantive changes in a merge request. You can choose to hide or show whitespace changes: -1. Go to your merge request, and select the **Changes** tab. -1. Above the list of changed files, select **(settings)** **Preferences** to - display the preferences menu. -1. Select or deselect **Show whitespace changes**: +1. Go to your merge request, and below the title, select **Changes**. +1. Before the list of changed files, select **Preferences** (**{settings}**). +1. Select or clear the **Show whitespace changes** checkbox: ![MR diff](img/merge_request_diff_v14_2.png) ## Mark files as viewed -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 [with a flag](../../../administration/feature_flags.md) named `local_file_reviews`. Enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296674) in GitLab 14.3. -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. +When reviewing a merge request with many files multiple times, you can ignore files +you've already reviewed. To hide files that haven't changed since your last review: -To mark a file as viewed: +1. Go to your merge request, and below the title, select **Changes**. +1. In the file's header, select the **Viewed** checkbox. -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. +Files marked as viewed are not shown to you again unless either: -Once checked, the file remains marked for that reviewer unless there are newly introduced -changes to its content or the checkbox is unchecked. +- New changes are made to its content. +- You clear the **Viewed** checkbox. -## Show merge request conflicts in diff +## Show merge request conflicts in diff **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. -> - [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](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `display_merge_conflicts_in_diff`. Disabled by default. -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +named `display_merge_conflicts_in_diff`. On GitLab.com, this feature is not available. +The feature is not ready for production use. To avoid displaying the changes that are already on target branch in the diff, we compare the merge request's source branch with HEAD of the target branch. When there are conflicts between the source and target branch, we show the -conflicts on the merge request diff as well: +conflicts on the merge request diff: ![Example of a conflict shown in a merge request diff](img/conflict_ui_v14_0.png) - -### Enable or disable merge request conflicts in diff **(FREE SELF)** - -Merge request conflicts in diff 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(:display_merge_conflicts_in_diff) -``` - -To disable it: - -```ruby -Feature.disable(:display_merge_conflicts_in_diff) -``` diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 30d463efa69..d735ce0ef91 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -53,7 +53,7 @@ See also the Code Climate list of [Supported Languages for Maintainability](http ## Code Quality in diff view **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in GitLab 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. > - [Disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0 due to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334116). > - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. @@ -248,9 +248,9 @@ This can be done: ### Using with merge request pipelines The configuration provided by the Code Quality template does not let the `code_quality` job -run on [pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md). +run on [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). -If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined. +If merge request pipelines is enabled, the `code_quality:rules` must be redefined. The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code quality` job: @@ -379,7 +379,7 @@ at the beginning of the file. ## Code Quality reports **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab Premium 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab 12.9. ![Code Quality Report](img/code_quality_report_13_11.png) @@ -392,7 +392,7 @@ After the Code Quality job completes: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. **(PREMIUM)** + Code Quality tab of the Pipeline Details page. ## Generate an HTML report @@ -591,3 +591,22 @@ plugins: If your merge requests do not show any code quality changes when using a custom tool, ensure that the line property is an `integer`. + +### Code Quality CI job with Code Climate plugins enabled fails with error "engine <plugin_name> ran for 900 seconds and was killed" + +If you enabled any of the Code Climate plugins, and the Code Quality CI job fails with the error below, +it's likely the job takes longer than the default timeout of 900 seconds. + +```shell +error: (CC::CLI::Analyze::EngineFailure) engine pmd ran for 900 seconds and was killed +Could not analyze code quality for the repository at /code +``` + +To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.gitlab.-ci.yml` file. + +For example: + +```yaml +variables: + TIMEOUT_SECONDS: 3600 +``` diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 3d3032bb193..0014c1ba994 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -29,21 +29,17 @@ To seamlessly navigate among commits in a merge request: ## View merge request commits in context -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12. -> - [Deployed behind a feature flag](../../feature_flags.md), enabled 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](#enable-or-disable-viewing-merge-request-commits-in-context). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. WARNING: -This feature is in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +This feature is in [beta](../../../policy/alpha-beta-support.md#beta-features) and is [incomplete](https://gitlab.com/groups/gitlab-org/-/epics/1192). -Previously merged commits can be added, but they can't be removed due to -[this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538). -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `context_commits`. +On GitLab.com, this feature is available. When reviewing a merge request, it helps to have more context about the changes made. That includes unchanged lines in unchanged files, and previous commits @@ -66,22 +62,3 @@ To view the changes done on those previously merged commits: 1. Scroll to **(file-tree)** **Compare** and select **previously merged commits**: ![Previously merged commits](img/previously_merged_commits_v14_1.png) - -### Enable or disable viewing merge request commits in context **(FREE SELF)** - -Viewing merge request commits in context 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(:context_commits) -``` - -To disable it: - -```ruby -Feature.disable(:context_commits) -``` diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 10c63421876..6900880417f 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -4,7 +4,7 @@ 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 --- -# Merge requests for confidential issues +# Merge requests for confidential issues **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a91679ffd63..637b682d603 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -17,7 +17,8 @@ the **Merge** button until you remove the **Draft** flag: ## Mark merge requests as drafts -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. +> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a draft: @@ -35,16 +36,12 @@ There are several ways to flag a merge request as a draft: is not a toggle, and adding this text again in a later commit doesn't mark the merge request as ready. -WARNING: -Adding `WIP:` to the start of the merge request's title still marks a merge request -as a draft. This feature is scheduled for removal in GitLab 14.0. Use `Draft:` instead. - ## Mark merge requests as ready When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: - **Viewing a merge request**: In the top right corner of the merge request, click **Mark as ready**. - Users with [Developer or greater permissions](../../permissions.md) + Users with at least the Developer role can also scroll to the bottom of the merge request description and click **Mark as ready**: ![Mark as ready](img/draft_blocked_merge_button_v13_10.png) @@ -79,11 +76,11 @@ draft merge requests: ## Pipelines for drafts -When the [pipelines for merged results](../../../ci/pipelines/pipelines_for_merged_results.md) +When the [merged results pipelines](../../../ci/pipelines/merged_results_pipelines.md) feature is enabled, draft merge requests run [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) only. -To run pipelines for merged results, you must +To run merged results pipelines, you must [mark the merge request as ready](#mark-merge-requests-as-ready). <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 3cb50195f5a..355661516a7 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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, howto --- # Fail Fast Testing **(PREMIUM)** @@ -42,8 +41,8 @@ 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/pipelines/merge_request_pipelines.md#prerequisites) -- [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) + - Use [Merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md#prerequisites) +- [Merged results pipelines](../../../ci/pipelines/merged_results_pipelines.md#enable-merged-results-pipelines) 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#override-included-configuration-values) this. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index ec509f58723..8699a42dd5d 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -56,7 +56,7 @@ request's page at the top-right side, or by using - [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](approvals/index.md#required-approvals) from your team. **(PREMIUM)** +- [Require approval](approvals/index.md#required-approvals) from your team. - [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. @@ -66,7 +66,7 @@ After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** +- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. - Preview continuous integration [pipelines on the merge request widget](widgets.md). - Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). @@ -162,7 +162,7 @@ enabled by default for all new merge requests, enable it in the This option is also visible in an existing merge request next to the merge request button and can be selected or deselected before merging. -It is only visible to users with the [Maintainer role](../../permissions.md) +It is only visible to users with the Maintainer role in the source project. If the user viewing the merge request does not have the correct diff --git a/doc/user/project/merge_requests/img/changes-inline_v14_8.png b/doc/user/project/merge_requests/img/changes-inline_v14_8.png Binary files differnew file mode 100644 index 00000000000..f3b6515283c --- /dev/null +++ b/doc/user/project/merge_requests/img/changes-inline_v14_8.png diff --git a/doc/user/project/merge_requests/img/changes-sidebyside_v14_8.png b/doc/user/project/merge_requests/img/changes-sidebyside_v14_8.png Binary files differnew file mode 100644 index 00000000000..981274dbb86 --- /dev/null +++ b/doc/user/project/merge_requests/img/changes-sidebyside_v14_8.png diff --git a/doc/user/project/merge_requests/img/collapse-comment_v14_8.png b/doc/user/project/merge_requests/img/collapse-comment_v14_8.png Binary files differnew file mode 100644 index 00000000000..93a802454f2 --- /dev/null +++ b/doc/user/project/merge_requests/img/collapse-comment_v14_8.png diff --git a/doc/user/project/merge_requests/img/expand-comment_v14_8.png b/doc/user/project/merge_requests/img/expand-comment_v14_8.png Binary files differnew file mode 100644 index 00000000000..a800eab83e9 --- /dev/null +++ b/doc/user/project/merge_requests/img/expand-comment_v14_8.png diff --git a/doc/user/project/merge_requests/img/file_by_file_v13_2.png b/doc/user/project/merge_requests/img/file_by_file_v13_2.png Binary files differdeleted file mode 100644 index e3114ebabad..00000000000 --- a/doc/user/project/merge_requests/img/file_by_file_v13_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png Binary files differdeleted file mode 100644 index e3a2ff7960c..00000000000 --- a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png Binary files differdeleted file mode 100644 index 1cdac5ef573..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png b/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png Binary files differnew file mode 100644 index 00000000000..1984defde9a --- /dev/null +++ b/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8222d696853..9872bd2e936 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -94,7 +94,7 @@ You cannot undo the deletion of a merge request. To delete a merge request: -1. Sign in to GitLab as a user with the project Owner [role](../../permissions.md). +1. Sign in to GitLab as a user with the project Owner role. Only users with this role can delete merge requests in a project. 1. Go to the merge request you want to delete, and select **Edit**. 1. Scroll to the bottom of the page, and select **Delete merge request**. @@ -137,3 +137,4 @@ For a web developer writing a webpage for your company's website: - [Suggest code changes](reviews/suggestions.md) - [Commits](commits.md) - [CI/CD pipelines](../../../ci/index.md) +- [Push options](../push_options.md) for merge requests diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 40859c6b572..cc4ad186771 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -1,13 +1,12 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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, howto --- # Load Performance Testing **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in GitLab 13.2. With Load Performance Testing, you can test the impact of any pending code changes to your application's backend in [GitLab CI/CD](../../../ci/index.md). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index aace1f58c62..6bfef6ab134 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -7,9 +7,9 @@ type: reference, concepts # 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 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in GitLab 12.2. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in GitLab 12.4. +> - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in GitLab 12.4. Merge request dependencies allows a required order of merging between merge requests to be expressed. If a merge request "depends on" another, diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index c34a8116625..280ae07b401 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -23,8 +23,8 @@ review merge requests in Visual Studio Code. ## 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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) from GitLab Premium to GitLab Free in 13.1. When you review a merge request, you can create comments that are visible only to you. When you're ready, you can publish them together in a single action. @@ -160,7 +160,7 @@ Multiline comments display the comment's line numbers above the body of the comm ## Bulk edit merge requests at the project level -Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. +Users with at least the Developer role can manage merge requests. When bulk-editing merge requests in a project, you can edit the following attributes: @@ -179,11 +179,11 @@ To update multiple project merge requests at the same time: 1. Select the appropriate fields and their values from the sidebar. 1. Click **Update all**. -## Bulk edit merge requests at the group level +## Bulk edit merge requests at the group level **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in GitLab 12.2. -Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. +Users with at least the Developer role can manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 1b2a35ba139..9868f2619ba 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -42,7 +42,7 @@ After the author applies a suggestion: 1. The suggestion is marked as **Applied**. 1. The thread is resolved. 1. GitLab creates a new commit with the changes. -1. If the user has the [Developer role](../../../permissions.md), GitLab pushes +1. If the user has the Developer role, GitLab pushes the suggested change directly into the codebase in the merge request's branch. ## Multi-line suggestions @@ -114,7 +114,7 @@ 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) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](../../../../policy/alpha-beta-support.md#alpha-features) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index f5ebfb3668c..a952c0550bc 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -28,6 +28,32 @@ You can configure merge request status checks for each individual project. These To learn more about use cases, feature discovery, and development timelines, see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). +## Lifecycle + +External status checks have an **asynchronous** workflow. Merge requests emit a merge request webhook payload to an external service whenever: + +- The merge request is changed. For example, title or description. +- Code is pushed to the source branch of the merge request. +- A comment is made in the merge request discussion. + +```mermaid +sequenceDiagram + Merge request->>+External service: Merge request payload + External service-->>-Merge request: Status check response + Note over External service,Merge request: Response includes SHA at HEAD +``` + +When the payload is received, the external service can then run any required processes before posting its response back to the merge request [using the REST API](../../../api/status_checks.md#set-status-of-an-external-status-check). + +Merge requests return a `409 Conflict` error to any responses that do not refer to the current `HEAD` of the source branch. As a result, it's safe for the external service to process and respond to out-of-date commits. + +External status checks have the following states: + +- `pending` - The default state. No response can been received by the merge request from the external service. +- `response received` - A response from the external service has been received and approved by it. + +Support for adding a `failed` state is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338827). + ## View the status checks on a project Within each project's settings, you can see a list of status checks added to the project: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 1f84964c619..bd54eda42f5 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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, howto --- # Test coverage visualization **(FREE)** @@ -40,6 +39,7 @@ Other coverage analysis frameworks support the format out of the box, for exampl - [Istanbul](https://istanbul.js.org/docs/advanced/alternative-reporters/#cobertura) (JavaScript) - [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.0.4/cmd.html#xml-reporting) (Python) +- [PHPUnit](https://github.com/sebastianbergmann/phpunit-documentation-english/blob/master/src/textui.rst#command-line-options) (PHP) Once configured, if you create a merge request that triggers a pipeline which collects coverage reports, the coverage is shown in the diff view. This includes reports @@ -52,6 +52,8 @@ from any job in any stage in the pipeline. The coverage displays for each line: Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. +Uploading a test coverage report does not enable [test coverage results in Merge Requests](../../../ci/pipelines/settings.md#add-test-coverage-results-to-a-merge-request-deprecated) or [code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). You must configure these separately. + ### Limits A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds @@ -133,6 +135,9 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ## Example test coverage configurations +This section provides test coverage configuration examples for different programming languages. You can also see a working example in +the [`coverage-report`](https://gitlab.com/gitlab-org/ci-sample-projects/coverage-report/) demonstration project. + ### JavaScript example The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) @@ -236,7 +241,7 @@ run tests: image: python:3 script: - pip install pytest pytest-cov - - coverage run -m pytest + - coverage run -m pytest - coverage report - coverage xml artifacts: @@ -244,6 +249,42 @@ run tests: cobertura: coverage.xml ``` +### PHP example + +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for PHP uses [PHPUnit](https://phpunit.readthedocs.io/) +to collect test coverage data and generate the report. + +With a minimal [`phpunit.xml`](https://phpunit.readthedocs.io/en/9.5/configuration.html) file (you may reference +[this example repository](https://gitlab.com/yookoala/code-coverage-visualization-with-php/)), you can run the test and +generate the coverage xml: + +```yaml +run tests: + stage: test + image: php:latest + variables: + XDEBUG_MODE: coverage + before_script: + - apt-get update && apt-get -yq install git unzip zip libzip-dev zlib1g-dev + - docker-php-ext-install zip + - pecl install xdebug && docker-php-ext-enable xdebug + - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" + - php composer-setup.php --install-dir=/usr/local/bin --filename=composer + - composer install + - composer require --dev phpunit/phpunit phpunit/php-code-coverage + script: + - php ./vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.cobertura.xml + artifacts: + reports: + cobertura: coverage.cobertura.xml +``` + +[Codeception](https://codeception.com/), through PHPUnit, also supports generating Cobertura report with +[`run`](https://codeception.com/docs/reference/Commands#run). The path for the generated file +depends on the `--coverage-cobertura` option and [`paths`](https://codeception.com/docs/reference/Configuration#paths) +configuration for the [unit test suite](https://codeception.com/docs/05-UnitTests). Configure `.gitlab-ci.yml` +to find Cobertura in the appropriate path. + ### C/C++ example The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with @@ -272,3 +313,62 @@ run tests: reports: cobertura: build/coverage.xml ``` + +### Go example + +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Go uses: + +- [`go test`](https://go.dev/doc/tutorial/add-a-test) to run tests. +- [`gocover-cobertura`](https://github.com/t-yuki/gocover-cobertura) to convert Go's coverage profile into the Cobertura XML format. + +This example assumes that [Go modules](https://go.dev/ref/mod) are being used. +Using Go modules causes paths within the coverage profile to be prefixed with your +project's module identifier, which can be found in the `go.mod` file. This +prefix must be removed for GitLab to parse the Cobertura XML file correctly. You can use the following `sed` command to remove the prefix: + +```shell +sed -i 's;filename=\"<YOUR_MODULE_ID>/;filename=\";g' coverage.xml +``` + +Replace the `gitlab.com/my-group/my-project` placeholder in the following example with your own module identifier to make it work. + +```yaml +run tests: + stage: test + image: golang:1.17 + script: + - go install + - go test . -coverprofile=coverage.txt -covermode count + - go run github.com/t-yuki/gocover-cobertura < coverage.txt > coverage.xml + - sed -i 's;filename=\"gitlab.com/my-group/my-project/;filename=\";g' coverage.xml + artifacts: + reports: + cobertura: coverage.xml +``` + +### Ruby example + +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Ruby uses + +- [`rspec`](https://rspec.info/) to run tests. +- [`simplecov`](https://github.com/simplecov-ruby/simplecov) and [`simplecov-cobertura`](https://github.com/dashingrocket/simplecov-cobertura) + to record the coverage profile and create a report in the Cobertura XML format. + +This example assumes: + +- That [`bundler`](https://bundler.io/) is being used for dependency management. + The `rspec`, `simplecov` and `simplecov-cobertura` gems have been added to your `Gemfile`. +- The `CoberturaFormatter` has been added to your `SimpleCov.formatters` + configuration within the `spec_helper.rb` file. + +```yaml +run tests: + stage: test + image: ruby:3.1 + script: + - bundle install + - bundle exec rspec + artifacts: + reports: + cobertura: coverage/coverage.xml +``` diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index 0a9a2a37bfe..741ac325cca 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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 description: "Test your code and display reports in merge requests" --- @@ -11,21 +10,21 @@ description: "Test your code and display reports in merge requests" GitLab has the ability to test the changes included in a feature branch and display reports or link to useful information directly from merge requests: -| Feature | Description | -|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | -| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the browser performance impact of pending code changes. | -| [Load Performance Testing](load_performance_testing.md) **(PREMIUM)** | Quickly determine the server performance impact of pending code changes. | -| [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | -| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | -| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | -| [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | -| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | -| [Multi-Project pipelines](../../../ci/pipelines/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | -| [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | -| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | -| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | +| Feature | Description | +|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | +| [Browser Performance Testing](browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | +| [Load Performance Testing](load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | +| [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | +| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | +| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | +| [License Compliance](../../compliance/license_compliance/index.md) | Manage the licenses of your dependencies. | +| [Metrics Reports](../../../ci/metrics_reports.md) | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | +| [Multi-Project pipelines](../../../ci/pipelines/multi_project_pipelines.md) | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | +| [Merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | +| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | +| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | ## Security Reports **(ULTIMATE)** diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 7c22b271ec2..05cc424e5ee 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ![burndown and burnup chart](img/burndown_and_burnup_charts_v13_6.png) -## Burndown charts **(PREMIUM)** +## Burndown charts > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. @@ -73,10 +73,8 @@ The chart indicates the project's progress throughout that milestone (for issues In particular, it shows how many issues were or are still open for a given day in the milestone's corresponding period. -The burndown chart can also be toggled to display the cumulative open issue -weight for a given day. When using this feature, make sure issue weights have -been properly assigned, since an open issue with no weight adds zero to the -cumulative value. +You can also toggle the burndown chart to display the +[cumulative open issue weight](#switch-between-number-of-issues-and-issue-weight) for a given day. ### Fixed burndown charts @@ -100,7 +98,7 @@ Therefore, when the milestone start date is changed, the number of opened issues change. Reopened issues are considered as having been opened on the day after they were last closed. -## Burnup charts **(PREMIUM)** +## Burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in GitLab 13.7. @@ -123,12 +121,21 @@ To view a group's burnup chart: ### How burnup charts work Burnup charts have separate lines for total work and completed work. The total line -shows when scope is reduced or added to a milestone. The completed work is a count -of issues closed. +shows changes to the scope of a milestone. When an open issue is moved to another +milestone, the "total issues" goes down but the "completed issues" stays the same. +The completed work is a count of issues closed. When an issue is closed, the "total +issues" remains the same and "completed issues" goes up. -Burnup charts can show either the total number of issues or total weight for each -day of the milestone. Use the toggle above the charts to switch between total -and weight. +## Switch between number of issues and issue weight + +In both burndown or burnup charts you can view them +either by the total number of issues +or the total weight for each day of the milestone. + +To switch between the two settings, select either **Issues** or **Issue weight** above the charts. + +When sorting by weight, make sure all your issues +have weight assigned, because issues with no weight don't show on the chart. <!-- ## Troubleshooting 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 differdeleted file mode 100644 index ffe1328b7d3..00000000000 --- a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png +++ /dev/null diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index fb61e123faf..4501cf500b0 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -53,35 +53,23 @@ If you're in a project and select **Issues > Milestones**, GitLab displays only ## Creating milestones -NOTE: -A permission level of [Developer or higher](../../permissions.md) is required to create milestones. - -### New project milestone - -To create a project milestone: - -1. In a project, go to **{issues}** **Issues > Milestones**. -1. Select **New milestone**. -1. Enter the title, an optional description, an optional start date, and an optional due date. -1. Select **New milestone**. - -![New project milestone](img/milestones_new_project_milestone.png) +Users with at least the Developer role can create milestones. -### New group milestone +Milestones can be created either at project or group level. -To create a group milestone: +To create a milestone: -1. In a group, go to **{issues}** **Issues > Milestones**. +1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Milestones**. 1. Select **New milestone**. 1. Enter the title, an optional description, an optional start date, and an optional due date. 1. Select **New milestone**. -![New group milestone](img/milestones_new_group_milestone_v13_5.png) +![New milestone](img/milestones_new_project_milestone.png) ## Editing milestones -NOTE: -A permission level of [Developer or higher](../../permissions.md) is required to edit milestones. +Users with at least the Developer role can edit milestones. To edit a milestone: @@ -155,23 +143,18 @@ There are also tabs below these that show the following: - Completed Issues (closed) - **Merge Requests**: Shows all merge requests assigned to the milestone. These are displayed in four columns named: - Work in progress (open and unassigned) - - Waiting for merge (open and unassigned) + - Waiting for merge (open and assigned) - Rejected (closed) - Merged - **Participants**: Shows all assignees of issues assigned to the milestone. - **Labels**: Shows all labels that are used in issues assigned to the milestone. -### Project Burndown Charts +### Burndown Charts -For project milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), showing the progress of completing a milestone. -![burndown chart](img/burndown_chart_v13_6.png) - -### Group Burndown Charts - -For group milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, -showing the progress of completing a milestone. +![burndown chart](img/burndown_and_burnup_charts_v13_6.png) ### Milestone sidebar diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 283ed0b61b9..82b1a824f7a 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -81,7 +81,7 @@ GitLab Pages website. You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you -must have the Administrator role in your domain's registrar (or control panel) to set it up with Pages. +must be an administrator in your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 10fbc57fa0b..65e1579001b 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -63,7 +63,7 @@ If the case of `404.html`, there are different scenarios. For example: You can configure redirects for your site using a `_redirects` file. To learn more, read the [redirects documentation](redirects.md). -## GitLab Pages Access Control **(FREE)** +## GitLab Pages Access Control To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 6c18fc158f5..8bb18905222 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -18,7 +18,7 @@ When a branch is protected, the default behavior enforces these restrictions on | Action | Who can do it | |:-------------------------|:------------------------------------------------------------------| -| Protect a branch | Maintainers only. | +| Protect a branch | At least the Maintainer role. | | Push to the branch | GitLab administrators and anyone with **Allowed** permission. (1) | | Force push to the branch | No one. | | Delete the branch | No one. | @@ -35,7 +35,7 @@ Administrators can set a default branch protection level in the Prerequisite: -- You must have at least the [Maintainer role](../permissions.md). +- You must have at least the Maintainer role. To protect a branch: @@ -52,7 +52,7 @@ The protected branch displays in the list of protected branches. Prerequisite: -- You must have at least the [Maintainer role](../permissions.md). +- You must have at least the Maintainer role. To protect multiple branches at the same time: @@ -75,7 +75,7 @@ The protected branch displays in the list of protected branches. ## Create a protected branch -Users with the Developer or higher [role](../permissions.md) can create a protected branch. +Users with at least the Developer role can create a protected branch. Prerequisites: @@ -217,16 +217,16 @@ for details about the pipelines security model. ## Delete a protected branch -Users with the [Maintainer role](../permissions.md) and greater can manually delete protected +Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: 1. Go to **Repository > Branches**. 1. Next to the branch you want to delete, select the **Delete** button (**{remove}**). 1. On the confirmation dialog, type the branch name and select **Delete protected branch**. -You can delete a protected branch from the UI only. -This prevents you from accidentally deleting a branch -from the command line or from a Git client application. +Protected branches can only be deleted by using GitLab either from the UI or API. +This prevents accidentally deleting a branch through local Git commands or +third-party Git clients. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index e4743c82a3b..7d071a45d63 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -22,12 +22,12 @@ This feature evolved out of [protected branches](protected_branches.md) By default: -- To create tags, you must have the [Maintainer role](../permissions.md). +- To create tags, you must have the Maintainer role. - No one can update or delete tags. ## Configuring protected tags -To protect a tag, you need to have at least the [Maintainer role](../permissions.md). +To protect a tag, you need to have at least the Maintainer role. 1. Go to the project's **Settings > Repository**. @@ -66,6 +66,26 @@ all matching tags: ![Protected tag matches](img/protected_tag_matches.png) +## Prevent tag creation with the same name as branches + +A tag and a branch with identical names can contain different commits. If your +tags and branches use the same names, users running `git checkout` +commands might check out the _tag_ `qa` when they instead meant to check out +the _branch_ `qa`. + +To prevent this problem: + +1. Identify the branch names you do not want used as tags. +1. As described in [Configuring protected tags](#configuring-protected-tags), + create a protected tag: + + - For the **Name**, provide a name, such as `stable`. You can also create a wildcard + like `stable-*` to match multiple names, like `stable-v1` and `stable-v2`. + - For **Allowed to Create**, select **No one**. + - Select **Protect**. + +Users can still create branches, but not tags, with the protected names. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 846d4732533..20dd37578fd 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Push Options **(FREE)** GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) -to perform various actions at the same time as pushing changes. Additionally, [Push Rules](../../push_rules/push_rules.md) offer server-side control and enforcement options. +to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. Currently, there are push options available for: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 21a080de404..8070c37db78 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -49,7 +49,7 @@ threads. Some quick actions might not be available to all subscription tiers. | Command | Issue | Merge request | Epic | Action | |:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/add_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | | `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | @@ -78,7 +78,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | | `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | | `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | @@ -89,7 +89,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | | `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | | `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | -| `/remove_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | | `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | | `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 747b41d07f2..8049ee9726d 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -393,7 +393,7 @@ deploy_to_production: To set a deploy freeze window in the UI, complete these steps: -1. Sign in to GitLab as a user with the [Maintainer role](../../permissions.md). +1. Sign in to GitLab as a user with the Maintainer role. 1. On the left sidebar, select **Project information**. 1. In the left navigation menu, navigate to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. @@ -480,7 +480,7 @@ to use the same URL. This is defined during [link creation](../../../api/release The format of the URL is: ```plaintext -https://host/namespace/project/releases/:release/downloads/:filepath +https://host/namespace/project/-/releases/:release/downloads/:filepath ``` If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org` @@ -498,7 +498,7 @@ namespace and `gitlab-runner` project on `gitlab.com`, for example: This asset has a direct link of: ```plaintext -https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 ``` The physical location of the asset can change at any time and the direct link remains unchanged. @@ -706,7 +706,7 @@ Here is an example of a release evidence object: ### Collect release evidence **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. @@ -714,7 +714,7 @@ Evidence collection snapshots are visible on the Releases page, along with the t ### Include report artifacts as release evidence **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. @@ -767,22 +767,22 @@ In the API: > [Changes were made to the Guest role access](https://gitlab.com/gitlab-org/gitlab/-/issues/335209) in GitLab 14.5. -- Users with the [Reporter role or above](../../../user/permissions.md#project-members-permissions) +- Users with at least the Reporter role have read and download access to the project releases. -- Users with the [Guest role](../../../user/permissions.md#project-members-permissions) +- Users with the Guest role have read and download access to the project releases. This includes associated Git-tag-names, release description, author information of the releases. However, other repository-related information, such as [source code](#source-code), [release evidence](#release-evidence) are redacted. ### Create, update, and delete a release and its assets -- Users with [Developer role or above](../../../user/permissions.md#project-members-permissions) +- Users with at least the Developer role have write access to the project releases and assets. - If a release is associated with a [protected tag](../protected_tags.md), the user must be [allowed to create the protected tag](../protected_tags.md#configuring-protected-tags) too. As an example of release permission control, you can allow only -[Maintainer role or above](../../../user/permissions.md#project-members-permissions) +users with at least the Maintainer role to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 65b7c4a9881..d706a0e8f8a 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -38,7 +38,7 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) To update the default branch name for an individual [project](../../index.md): -1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. +1. Sign in to GitLab with at least the Maintainer role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close @@ -57,8 +57,8 @@ GitLab administrators can configure a new default branch name at the ### Instance-level custom initial branch name **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/325163) in GitLab 13.12. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2 [with a flag](../../../../administration/feature_flags.md) named `global_default_branch_name`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/325163) in GitLab 13.12. Feature flag `global_default_branch_name` removed. GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual @@ -129,7 +129,7 @@ renames a Git repository's (`example`) default branch. git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main ``` -1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) +1. Sign in to GitLab with at least the Maintainer role and follow the instructions to [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 1ab21286a8e..b085372c8f2 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -27,16 +27,15 @@ To fork an existing project in GitLab: 1. Select the project to fork to: - Recommended method. Below **Select a namespace to fork the project**, identify - the project you want to fork to, and click **Select**. Only namespaces you have - Developer and higher [permissions](../../permissions.md) for are shown. + the project you want to fork to, and click **Select**. Only namespaces where you have + at least the Developer role for are shown. ![Choose namespace](img/forking_workflow_choose_namespace_v13_10.png) - Experimental method. If your GitLab administrator has - [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read + enabled the experimental fork project form, read [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). - Only namespaces you have at least the Developer - [role](../../permissions.md) for are shown. + Only namespaces where you have at least the Developer role for are shown. NOTE: The project path must be unique in the namespace. @@ -85,14 +84,14 @@ You can unlink your fork from its upstream project in the [advanced settings](.. ## Create a fork with the fork project form **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../../user/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](#enable-or-disable-the-fork-project-form). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11 [with a flag](../../../administration/feature_flags.md) named `fork_project_form`. Disabled by default. +> - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64967) in GitLab 13.8. -This experimental version of the fork project form is available only if your GitLab -administrator has [enabled it](#enable-or-disable-the-fork-project-form): +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `fork_project_form`. +On GitLab.com, this feature is available. + +This version of the fork project form is experimental: ![Choose namespace](img/fork_form_v13_10.png) @@ -103,23 +102,3 @@ To use it, follow the instructions at [Creating a fork](#creating-a-fork) and pr - The project slug. - Optional. The project description. - The visibility level for your fork. - -### Enable or disable the fork project form **(FREE SELF)** - -The new [fork project form](#create-a-fork-with-the-fork-project-form) 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(:fork_project_form) -``` - -To disable it: - -```ruby -Feature.disable(:fork_project_form) -``` diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 0c5c0d5fa7c..f5cea8a8075 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -273,7 +273,7 @@ To remove a GPG key from your account: ## Rejecting commits that are not signed **(PREMIUM)** You can configure your project to reject commits that aren't GPG-signed -via [push rules](../../../../push_rules/push_rules.md). +via [push rules](../push_rules.md). ## GPG signing API diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index c8950d39f28..cddbc6fd891 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -37,7 +37,7 @@ Mirror a repository when: Prerequisite: -- You must have at least the [Maintainer role](../../../permissions.md) for the project. +- You must have at least the Maintainer role for the project. - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. @@ -45,8 +45,8 @@ Prerequisite: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original - repository is only displayed to users with the [Maintainer role](../../../permissions.md) - or the [Owner role](../../../permissions.md) for the mirrored project. + repository is only displayed to users with the Maintainer role + or the Owner role for the mirrored project. 1. Select a **Mirror direction**. 1. If you entered a `ssh://` URL, select either: - **Detect host keys**: GitLab fetches the host keys from the server and displays the fingerprints. @@ -87,7 +87,7 @@ While mirrors are scheduled to update automatically, you can force an immediate Prerequisite: -- You must have at least the [Maintainer role](../../../permissions.md) for the project. +- You must have at least the Maintainer role for the project. 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md new file mode 100644 index 00000000000..bb473a2830b --- /dev/null +++ b/doc/user/project/repository/push_rules.md @@ -0,0 +1,288 @@ +--- +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" +--- + +# Push rules **(PREMIUM)** + +Gain additional control over what can and can't be pushed to your repository by using +regular expressions to reject pushes based on commit contents, branch names or file details. + +GitLab already offers [protected branches](../protected_branches.md), but there are +cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or +enforcing a special format for commit messages. + +Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you +can enable in a user-friendly interface. They are defined either: + +- Globally if you are an administrator. +- Per project, so you can have different rules applied to different + projects depending on your needs. + +## Use cases + +Every push rule could have its own use case, but let's consider some examples. + +### Commit messages with a specific reference + +Let's assume you have the following requirements for your workflow: + +- every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.` +- users should not be able to remove Git tags with `git push` + +Write a regular expression that requires the mention +of a Jira issue in the commit message, like `JIRA\-\d+`. + +Now when a user tries to push a commit with a message `Bugfix`, their push is +declined. Only pushing commits with messages like `Bugfix according to JIRA-123` +is accepted. + +### Restrict branch names + +If your company has a strict policy for branch names, you may want the branches to start +with a certain name. This approach enables different +GitLab CI/CD jobs (such as `feature`, `hotfix`, `docker`, `android`) that rely on the +branch name. + +Your developers may not remember that policy, so they might push to +various branches, and CI pipelines might not work as expected. By restricting the +branch names globally in Push Rules, such mistakes are prevented. +All branch names that don't match your push rule are rejected. + +Note that the name of your default branch is always allowed, regardless of the branch naming +regular expression (regex) specified. GitLab is configured this way +because merges typically have the default branch as their target. +If you have other target branches, include them in your regex. (See [Enabling push rules](#enabling-push-rules)). + +The default branch also defaults to being a [protected branch](../protected_branches.md), +which already limits users from pushing directly. + +Some example regular expressions you can use in push rules: + +- `^JIRA-` Branches must start with `JIRA-`. +- `-JIRA$` Branches must end with `-JIRA`. +- `^[a-z0-9\\-]{4,15}$` Branches must be between `4` and `15` characters long, + accepting only lowercase letters, numbers and dashes. + +#### Default restricted branch names + +> Introduced in GitLab 12.10. + +By default, GitLab restricts certain formats of branch names for security purposes. +40-character hexadecimal names, similar to Git commit hashes, are prohibited. + +### Custom Push Rules **(PREMIUM SELF)** + +It's possible to create custom push rules rather than the push rules available in +**Admin Area > Push Rules** by using more advanced server hooks. + +See [server hooks](../../../administration/server_hooks.md) for more information. + +## Enabling push rules + +You can create push rules for all new projects to inherit, but they can be overridden +at the project level or the [group level](../../group/index.md#group-push-rules). + +To create global push rules: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Push Rules**. + +To override global push rules in a project's settings: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Set the rule you want. +1. Select **Save push rules**. + +The following options are available: + +| Push rule | Description | +|---------------------------------|-------------| +| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags can be deleted through the web UI. | +| Check whether the commit author is a GitLab user | Restrict commits to existing GitLab users (checked against their emails). <sup>1</sup> | +| Reject unverified users | GitLab rejects any commit that was not committed by the same user as the user who pushed it, or where the committer's email address is not [confirmed](../../../security/user_email_confirmation.md). | +| Check whether commit is signed through GPG | Reject commit when it is not signed through GPG. Read [signing commits with GPG](gpg_signed_commits/index.md). | +| Prevent pushing secret files | GitLab rejects any files that are likely to contain secrets. See the [forbidden file names](#prevent-pushing-secrets-to-the-repository). | +| Require expression in commit messages | Only commit messages that match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | +| Reject expression in commit messages | Only commit messages that do not match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | +| Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow all branch names. | +| Restrict by commit author's email | Only commit author's email that match this regular expression are allowed to be pushed. <sup>1</sup> <sup>2</sup> Leave empty to allow any email. | +| Prohibited file names | Any committed filenames that match this regular expression and do not already exist in the repository are not allowed to be pushed. <sup>2</sup> Leave empty to allow any filenames. See [common examples](#prohibited-file-names). | +| Maximum file size | Pushes that contain added or updated files that exceed this file size (in MB) are rejected. Set to 0 to allow files of any size. Files tracked by Git LFS are exempted. | + +1. Checks both the commit author and committer. +1. GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules, and you can test them at the [regex101 regex tester](https://regex101.com/). + +### Caveat to "Reject unsigned commits" push rule + +This push rule ignores commits that are authenticated and created by GitLab +(either through the UI or API). When the **Reject unsigned commits** push rule is +enabled, unsigned commits may still show up in the commit history if a commit was +created **in** GitLab itself. As expected, commits created outside GitLab and +pushed to the repository are rejected. For more information about how GitLab +plans to fix this issue, read [issue #19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185). + +#### "Reject unsigned commits" push rule disables Web IDE + +In 13.10, if a project has the "Reject unsigned commits" push rule, the user is not allowed to +commit through GitLab Web IDE. + +To allow committing through the Web IDE on a project with this push rule, a GitLab administrator +must disable the feature flag `reject_unsigned_commits_by_gitlab`. This can be done through a +[rails console](../../../administration/operations/rails_console.md) and running: + +```ruby +Feature.disable(:reject_unsigned_commits_by_gitlab) +``` + +## Prevent pushing secrets to the repository + +> Moved to GitLab Premium in 13.9. + +Secrets, such as credential files and SSH private keys, should never be committed to a version control +system. In GitLab, you can use a predefined list of files to block those files from a +repository. Any merge request containing a file matching the list is blocked from being merged. +Files already committed to the repository are not restricted by this push rule. + +Files blocked by this rule are listed below. For a complete list of criteria, see +[`files_denylist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml). + +- AWS CLI credential blobs: + + - `.aws/credentials` + - `aws/credentials` + - `homefolder/aws/credentials` + +- Private RSA SSH keys: + + - `/ssh/id_rsa` + - `/.ssh/personal_rsa` + - `/config/server_rsa` + - `id_rsa` + - `.id_rsa` + +- Private DSA SSH keys: + + - `/ssh/id_dsa` + - `/.ssh/personal_dsa` + - `/config/server_dsa` + - `id_dsa` + - `.id_dsa` + +- Private ED25519 SSH keys: + + - `/ssh/id_ed25519` + - `/.ssh/personal_ed25519` + - `/config/server_ed25519` + - `id_ed25519` + - `.id_ed25519` + +- Private ECDSA SSH keys: + + - `/ssh/id_ecdsa` + - `/.ssh/personal_ecdsa` + - `/config/server_ecdsa` + - `id_ecdsa` + - `.id_ecdsa` + +- Private ECDSA_SK SSH keys (GitLab 14.8 and later): + + - `/ssh/id_ecdsa_sk` + - `/.ssh/personal_ecdsa_sk` + - `/config/server_ecdsa_sk` + - `id_ecdsa_sk` + - `.id_ecdsa_sk` + +- Private ED25519_SK SSH keys (GitLab 14.8 and later): + + - `/ssh/id_ed25519_sk` + - `/.ssh/personal_ed25519_sk` + - `/config/server_ed25519_sk` + - `id_ed25519_sk` + - `.id_ed25519_sk` + +- Any files ending with these suffixes: + + - `*.pem` + - `*.key` + - `*.history` + - `*_history` + +### Prevent pushing secrets to all projects + +To set a global push rule to prevent pushing secrets to all projects: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Push Rules**. +1. Expand **Push rules**. +1. Select **Prevent pushing secret files**. +1. Select **Save push rules**. + +### Prevent pushing secrets to a project + +The push rule of a project overrides the global push rule. + +To prevent pushing secrets to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Select **Prevent pushing secret files**. +1. Select **Save push rules**. + +## Prohibited file names + +> Moved to GitLab Premium in 13.9. + +Each filename contained in a Git push is compared to the regular expression in this field. Filenames in Git consist of both the file's name and any directory that may precede it. A singular regular expression can contain multiple independent matches used as exclusions. File names can be broadly matched to any location in the repository, or restricted to specific locations. Filenames can also be partial matches used to exclude file types by extension. + +The following examples make use of regex string boundary characters which match the beginning of a string (`^`), and the end (`$`). They also include instances where either the directory path or the filename can include `.` or `/`. Both of these special regex characters have to be escaped with a backslash `\\` to be used as normal characters in a match condition. + +Example: prevent pushing any `.exe` files to any location in the repository. This uses a partial match, which matches any filename that contains `.exe` at the end: + +```plaintext +\.exe$ +``` + +Example: prevent a specific configuration file in the repository root from being pushed: + +```plaintext +^config\.yml$ +``` + +Example: prevent a specific configuration file in a known directory from being pushed: + +```plaintext +^directory-name\/config\.yml$ +``` + +Example: prevent the specific file named `install.exe` from being pushed to any +location in the repository. The parenthesized expression `(^|\/)` matches either +a file following a directory separator or a file in the root directory of the repository: + +```plaintext +(^|\/)install\.exe$ +``` + +Example: combining all of the above in a single expression. The preceding expressions rely +on the end-of-string character `$`. We can move that part of each expression to the +end of the grouped collection of match conditions where it is appended to all matches: + +```plaintext +(\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$ +``` + +<!-- ## 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/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 23cead7e8a7..37b16d90d93 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Reduce repository size +# Reduce repository size **(FREE)** Git repositories become larger over time. When large files are added to a Git repository: @@ -193,7 +193,7 @@ When using repository cleanup, note: Repository size limits: - Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) - on self-managed instances. **(PREMIUM SELF)** +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md) on self-managed instances. - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index f9d9af3e672..27ef14d31c5 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,8 +1,7 @@ --- 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: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Sign commits and tags with X.509 certificates **(FREE)** @@ -335,7 +334,7 @@ step of the previous [main verification checks](#main-verification-checks). signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) ``` - 1. If this fails, add the missing certificate(s) required to establish trust + 1. If this fails, add the missing certificates required to establish trust [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). 1. After adding more certificates, (if these troubleshooting steps then pass) @@ -347,7 +346,7 @@ step of the previous [main verification checks](#main-verification-checks). pp signature.__send__(:p7).certificates ; nil ``` -Ensure any additional intermediate certificate(s) and the root certificate are added +Ensure any additional intermediate certificates and the root certificate are added to the certificate store. For consistency with how certificate chains are built on web servers: diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 5fe0e0ef3a2..d549a22910a 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -40,7 +40,7 @@ can create a new requirement. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To create a requirement: @@ -70,7 +70,7 @@ You can edit a requirement from the requirements list page. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To edit a requirement: @@ -86,7 +86,7 @@ you're in the **Open** tab. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To archive a requirement, select **Archive** (**{archive}**). @@ -98,7 +98,7 @@ You can view the list of archived requirements in the **Archived** tab. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. ![archived requirements list](img/requirements_archived_list_view_v13_1.png) @@ -217,7 +217,7 @@ requirements_confirmation: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. -You must have at least the Reporter [role](../../permissions.md). +You must have at least the Reporter role. You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) with the columns `title` and `description`. @@ -291,7 +291,7 @@ audit and regulatory compliance tasks. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To export requirements: diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 1b30f14ac90..1e5b818c99d 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -87,7 +87,7 @@ To improve your project's security, we recommend the following: Unblocked email spam can result in many spam issues being created. The unique internal email address is visible to project members at least -the Reporter [role](../permissions.md) in your GitLab instance. +the Reporter role in your GitLab instance. An external user (issue creator) cannot see the internal email address displayed in the information note. @@ -333,3 +333,10 @@ Note that: Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user does not count toward the license limit count. + +## Troubleshooting Service Desk + +### Emails to Service Desk do not create issues + +Your emails might be ignored because they contain one of the +[email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 06bdf4ca14b..8cee567ae93 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -122,8 +122,7 @@ As described in the API documentation, the query may return an import error or e The following items are imported but changed slightly: -- Project members with the [Owner role](../../permissions.md) - are imported as Maintainers. +- Project members with the Owner role are imported as Maintainers. - If an imported project contains merge requests originating from forks, then new branches associated with such merge requests are created in a project during the import/export. Thus, the number of branches in the exported project might be bigger than in the original project. @@ -160,6 +159,8 @@ Imported users can be mapped by their public email addresses on self-managed ins for mapping to work correctly. - For contributions to be mapped correctly, users must be an existing member of the namespace, or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. +- Imported users are set as [direct members](../members/index.md) + in the imported project. 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/). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 9df545b52ec..4c6be3511f2 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -16,7 +16,7 @@ In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epic GitLab displays a search box to help you find the settings you want to view. NOTE: -Only users who have the [Maintainer role](../../permissions.md) for the project and administrators can +Only users who have the Maintainer role for the project and administrators can access project settings. ## General settings @@ -93,7 +93,7 @@ executed in place of the local project's `gitlab-ci.yml` file. As part of this p files are merged together any time the pipeline runs. Jobs and variables defined in the compliance pipeline can't be changed by variables in the local project's `gitlab-ci.yml` file. -When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/#scan-execution-policies), +When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see [Enforce scan execution](../../application_security/#enforce-scan-execution). @@ -249,7 +249,7 @@ Use the switches to enable or disable the following features: |:---------------------------------|:--------------------------|:--------------| | **Issues** | ✓ | Activates the GitLab issues tracker. | | **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | +| **Merge requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | | **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | | **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | @@ -281,7 +281,7 @@ Some features depend on others: - If you disable **Repository** functionality, GitLab also disables the following features for your project: - - **Merge Requests** + - **Merge requests** - **CI/CD** - **Container Registry** - **Git Large File Storage** @@ -360,7 +360,7 @@ available in project listings. Only project owners and administrators have the To find an archived project: -1. Sign in to GitLab as the project owner or a user with the Administrator role. +1. Sign in to GitLab as the project owner or a user with administrator access. 1. If you: - Have the project's URL, open the project's page in your browser. - Don't have the project's URL: @@ -404,11 +404,17 @@ NOTE: Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to transfer a project. -You can transfer an existing project into a [group](../../group/index.md) if: +You can transfer an existing project into a [group](../../group/index.md). -- You have at least **Maintainer** [role](../../permissions.md#project-members-permissions) in that group. -- You're at least an **Owner** of the project to be transferred. +Prerequisites: + +- You must have at least the Maintainer role in that group. +- You must be the Owner of that project. - The group to which the project is being transferred to must allow creation of new projects. +- The project must not contain any [container images](../../packages/container_registry/index.md#limitations). + - If you transfer a project to a different root namespace, + the project must not contain any + [NPM packages](../../packages/npm_registry/index.md#limitations). To transfer a project: @@ -423,8 +429,8 @@ read what happens with the [redirects from the old project to the new one](../repository/index.md#what-happens-when-a-repository-path-changes). NOTE: -GitLab administrators can use the administration interface to move any project to any -namespace if needed. +GitLab administrators can use the [administration interface](../../admin_area/index.md#administering-projects) +to move any project to any namespace if needed. ##### Transferring a GitLab.com project to a different subscription tier diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 3fcfe202d38..aa30c576c7c 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -42,7 +42,7 @@ To create a project access token: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. -1. Enter a name. +1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). @@ -84,16 +84,16 @@ To enable or disable project access token creation for all projects in a top-lev Even when creation is disabled, you can still use and revoke existing project access tokens. -## Project bot users +## Bot users for projects > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Bot users for projects are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). Each time you create a project access token, a bot user is created and added to the project. These bot users do not count as licensed seats. -The bot users have [permissions](../../permissions.md#project-members-permissions) that correspond with the +The bot users for projects have [permissions](../../permissions.md#project-members-permissions) that correspond with the selected role and [scope](#scopes-for-a-project-access-token) of the project access token. - The name is set to the name of the token. @@ -106,7 +106,7 @@ selected role and [scope](#scopes-for-a-project-access-token) of the project acc API calls made with a project access token are associated with the corresponding bot user. -Bot users: +Bot users for projects: - Are included in a project's member list but cannot be modified. - Cannot be added to any other project. @@ -114,5 +114,6 @@ Bot users: When the project access token is [revoked](#revoke-a-project-access-token): - The bot user is deleted. -- All records are moved to a system-wide user with the username `Ghost User`. For more information, see - [associated records](../../profile/account/delete_account.md#associated-records). +- All records are moved to a system-wide user with the username [Ghost User](../../profile/account/delete_account.md#associated-records). + +See also [Bot users for groups](../../group/settings/group_access_tokens.md#bot-users-for-groups). diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 50b1a3a929d..072f5bf1927 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -12,6 +12,14 @@ description: "The static site editor enables users to edit content on static web > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. > - Non-Markdown content blocks not editable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. > - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) +for use in GitLab 14.7, and is planned for +[removal](https://gitlab.com/groups/gitlab-org/-/epics/7351) in GitLab 15.0. +Users should instead use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md). Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 6ceb8c94934..5f747d99ce7 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -8,76 +8,81 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Time tracking **(FREE)** -With time tracking you can track estimates and time spent on issues and merge -requests in GitLab. +You can estimate and track the time you spend on [issues](issues/index.md) +and [merge requests](merge_requests/index.md). + +Then you can [view a report](#view-a-time-tracking-report) that shows totals over time. Use time tracking for these tasks: - Record the time spent working on an issue or a merge request. - Add or update an estimate of the total time to complete an issue or a merge -request. + 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 shows up on the issue and merge request sidebar: +To enter and remove time tracking data, you must use [quick actions](quick_actions.md). +Type all quick actions on their own lines. +If you use any quick action more than once in a single comment, only its last occurrence is applied. + +You can see the data about time tracking on the right sidebar in issues and merge requests: ![Time tracking in the sidebar](img/time_tracking_sidebar_v13_12.png) -## How to enter data +## Estimates -Time tracking uses two [quick actions](quick_actions.md): `/spend` and `/estimate`. +The estimate is designed to show the total time needed to complete an issue or merge request. -If you use either quick action more than once in a single comment, only the last occurrence is applied. +You can see the estimated time remaining when you hover over the time tracking information in the right sidebar. -Below is an example of how you can use those new quick actions inside a comment. +![Estimated time remaining](img/remaining_time_v14_2.png) -![Time tracking example in a comment](img/time_tracking_example_v12_2.png) +### Add an estimate -Adding time entries (time spent or estimates) is limited to project members -with [Reporter and higher permission levels](../permissions.md). +Prerequisites: -### Estimates +- You must have at least the Reporter role for the project. -To enter an estimate, type `/estimate`, followed by the time. +To enter an estimate, use the `/estimate` [quick action](quick_actions.md), followed by the time. For example, if you need to enter an estimate of 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/estimate 1mo 2w 3d 4h 5m`. -Check the [time units you can use](#configuration). +Check the [time units you can use](#available-time-units). -The estimate is designed to show the total estimated time. The estimated -time remaining is automatically calculated and displayed when hovering over -the time tracking information in the right sidebar. +An issue or a merge request can have only one estimate. +Every time you enter a new time estimate, it overwrites the previous value. -![Estimated time remaining](img/remaining_time_v14_2.png) +### Remove an estimate -An issue or a merge request can have only one estimate. Every time you enter a -new time estimate, it overwrites the previous value. +Prerequisites: -To remove an estimation entirely, use `/remove_estimate`. +- You must have at least the Reporter role for the project. -### Time spent +To remove an estimate entirely, use the `/remove_estimate` [quick action](quick_actions.md). -To enter time spent, type `/spend`, followed by the time. +## Time spent -For example, if you need -to log 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/spend 1mo 2w 3d 4h 5m`. -Check the [time units you can use](#configuration). +As you work, you can log the time you've spent. Every new time spent entry is added to the current total time spent for the issue or the merge request. -To subtract time, enter a negative value. For example, `/spend -3d` removes three -days from the total time spent. You can't go below 0 minutes of time spent, -so if you remove more time than already entered, GitLab ignores the subtraction. +### Add time spent -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 type `/spend 1h 2021-01-31`. If you supply a date in the future, the -command fails and no time is logged. +Prerequisites: + +- You must have at least the Reporter role for the project. + +To enter time spent, use the `/spend` [quick action](quick_actions.md), followed by the time. + +For example, if you need +to log 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/spend 1mo 2w 3d 4h 5m`. +Check the [time units you can use](#available-time-units). -To add a timelog entry with a note, create a comment with a description and the quick action. -It then shows in the timelog "Summary/Notes" column. For example: +To add a [time tracking report](#view-a-time-tracking-report) entry with a note, create a comment +with a description and the quick action. +It then shows in the time tracking report **Summary/Notes** column. For example: ```plaintext Draft MR and respond to initial comments @@ -85,7 +90,29 @@ Draft MR and respond to initial comments /spend 30m ``` -To remove all the time spent at once, use `/remove_time_spent`. +### Add time spent on a specific date + +Prerequisites: + +- You must have at least the Reporter role for the project. + +You can log time in the past by providing a date after the time. +For example, to log 1 hour of time spent on 31 January 2021, +type `/spend 1h 2021-01-31`. + +If you type a future date, no time is logged. + +### Remove time spent + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To subtract time, enter a negative value. For example, `/spend -3d` removes three +days from the total time spent. You can't go below 0 minutes of time spent, +so if you remove more time than already entered, GitLab ignores the subtraction. + +To remove all the time spent at once, use the `/remove_time_spent` [quick action](quick_actions.md). ## View a time tracking report @@ -93,35 +120,32 @@ To remove all the time spent at once, use `/remove_time_spent`. You can view a breakdown of time spent on an issue or merge request. -Prerequisites: - -- You must have at least the [Reporter role](../permissions.md#project-members-permissions) for a project. +To view a time tracking report: -To view a time tracking report, go to an issue or a merge request and select **Time tracking report** -in the right sidebar. +1. Go to an issue or a merge request. +1. In the right sidebar, select **Time tracking report**. ![Time tracking report](img/time_tracking_report_v13_12.png) The breakdown of spent time is limited to a maximum of 100 entries. -## Configuration +## Available time units The following time units are available: -| Time unit | What to type | Default conversion rate | -| --------- | ------------ | ----------------------- | -| Month | `mo` | 4w | -| Week | `w` | 5d | -| Day | `d` | 8h | -| Hour | `h` | 60m | -| Minute | `m` | | +| Time unit | What to type | Conversion rate | +| --------- | --------------------------- | --------------- | +| Month | `mo`, `month`, or `months` | 4w (160h) | +| Week | `w`, `week`, or `weeks` | 5d (40h) | +| Day | `d`, `day`, or `days` | 8h | +| Hour | `h`, `hour`, or `hours` | 60m | +| Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. -In GitLab self-managed instances, you can limit the display of time units to -hours. +In GitLab self-managed instances, you can limit the display of time units to hours. To do so: 1. On the top bar, select **Menu > Admin**. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 731fed2595a..2c499af123c 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -22,7 +22,7 @@ Group wikis are similar to [project wikis](index.md), with a few limitations: For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). -Similar to project wikis, group members with the [Developer role](../../permissions.md#group-members-permissions) +Similar to project wikis, group members with at least the Developer role and higher can edit group wikis. Group wiki repositories can be moved using the [Group repository storage moves API](../../../api/group_repository_storage_moves.md). @@ -40,7 +40,7 @@ To access a group wiki: > Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247). -Users with the [Owner role](../../permissions.md) in a group can +Users with the Owner role in a group can [import and export group wikis](../../group/settings/import_export.md) when importing or exporting a group. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 95ea1b4d0bc..33f6c32d334 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -74,7 +74,7 @@ to be used as your wiki's home page. To create it: ## Create a new wiki page -Users with the [Developer role](../../permissions.md) can create new wiki pages: +Users with at least the Developer role can create new wiki pages: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -137,7 +137,7 @@ may not be able to check out the wiki locally afterward. ## Edit a wiki page -You need at least the [Developer role](../../permissions.md) to edit a wiki page: +You need at least the Developer role to edit a wiki page: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -156,7 +156,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need at least the [Developer role](../../permissions.md) to delete a wiki page: +You need at least the Developer role to delete a wiki page: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -169,7 +169,7 @@ You need at least the [Developer role](../../permissions.md) to delete a wiki pa ## Move a wiki page -You need at least the [Developer role](../../permissions.md) to move a wiki page: +You need at least the Developer role to move a wiki page: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -239,7 +239,7 @@ Commits to wikis are not counted in [repository analytics](../../analytics/repos > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -You need at least the [Developer role](../../permissions.md) to customize the wiki +You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: @@ -323,9 +323,17 @@ Previously added wiki pages are preserved in case you want to re-enable the wiki. To re-enable it, repeat the process to disable the wiki but toggle it on (in blue). -## Content Editor **(FREE)** +## Content Editor -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345398) switching between editing experiences in GitLab 14.7 [with a flag](../../../administration/feature_flags.md) named `wiki_switch_between_content_editor_raw_markdown`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, ask an administrator to +[disable the feature flag](../../../administration/feature_flags.md) named +`wiki_switch_between_content_editor_raw_markdown`. +On GitLab.com, this feature is available. GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 61eca19a67b..9cfcaf4ee81 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -99,6 +99,8 @@ To create a blank project: slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - In the **Project description (optional)** field, enter the description of your project's dashboard. + - In the **Project target (optional)** field, select your project's deployment target. + This information helps GitLab better understand its users and their deployment requirements. - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, change the **Visibility Level**. - To create README file so that the Git repository is initialized, has a default branch, and @@ -297,6 +299,29 @@ To delete a project: 1. Select **Delete project** 1. Confirm this action by completing the field. +## Projects pending deletion **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. +> - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. +> - [Available to all users](https://gitlab.com/gitlab-org/gitlab/-/issues/346976) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available to all users. To make it available for administrators only, +ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. +On GitLab.com, this feature is available to all users. + +When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), +projects within that group are not deleted immediately, but only after a delay. To access a list of all projects that are pending deletion: + +1. On the top bar, select **Menu > Projects > Explore projects**. +1. Select the **Pending deletion** tab (in GitLab 14.6 and later) or the **Deleted projects** tab (GitLab 14.5 and earlier). + +Listed for each project is: + +- The time the project was marked for deletion. +- The time the project is scheduled for final deletion. +- A **Restore** link to stop the project being eventually deleted. + ## View project activity To view the activity of a project: |