diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-03-18 23:02:30 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-03-18 23:02:30 +0300 |
| commit | 41fe97390ceddf945f3d967b8fdb3de4c66b7dea (patch) | |
| tree | 9c8d89a8624828992f06d892cd2f43818ff5dcc8 /doc/user/project | |
| parent | 0804d2dc31052fb45a1efecedc8e06ce9bc32862 (diff) | |
Add latest changes from gitlab-org/gitlab@14-9-stable-eev14.9.0-rc42
Diffstat (limited to 'doc/user/project')
97 files changed, 1358 insertions, 982 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 79d395d51c3..2f9e04fb828 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Badges are a unified way to present condensed pieces of information about your projects. They consist of a small image and a URL that the image points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), -[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the +[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the project maintainers.  diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 77cf04cc7eb..344caed7449 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Canary Deployments **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in GitLab 9.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of @@ -35,7 +35,7 @@ your pods fleet and watch their behavior as a percentage of your user base visits the temporarily deployed feature. If all works well, you can deploy the feature to production knowing that it shouldn't cause any problems. -Canary deployments are also especially useful for backend refactors, performance +Canary deployments are also especially required for backend refactors, performance improvements, or other changes where the user interface doesn't change, but you want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, @@ -50,7 +50,7 @@ this document. Canary deployments require that you properly configure deploy boards: 1. Follow the steps to [enable deploy boards](deploy_boards.md#enabling-deploy-boards). -1. To track canary deployments you need to label your Kubernetes deployments and +1. To track canary deployments you must label your Kubernetes deployments and pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy) template for canary deployments that GitLab provides. @@ -60,19 +60,19 @@ Any other track label is considered `canary` (temporary). This allows GitLab to discover whether a deployment is stable or canary (temporary). Once all of the above are set up and the pipeline has run at least once, -navigate to the environments page under **Pipelines > Environments**. +Go to the environments page under **Pipelines > Environments**. As the pipeline executes, deploy boards clearly mark canary pods, enabling -quick and easy insight into the status of each environment and deployment. +quick and clear insight into the status of each environment and deployment. Canary deployments are marked with a yellow dot in the deploy board so that you -can easily notice them. +can quickly notice them.  ### Advanced traffic control with Canary Ingress (DEPRECATED) -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Free in GitLab 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: @@ -82,7 +82,7 @@ Canary deployments can be more strategic with [Canary Ingress](https://kubernete which is an advanced traffic routing service that controls incoming HTTP requests between stable and canary deployments based on factors such as weight, sessions, cookies, and others. GitLab uses this service in its [Auto Deploy architecture](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#v2-chart-resource-architecture) -to let users easily and safely roll out their new deployments. +to let users quickly and safely roll out their new deployments. #### How to set up a Canary Ingress in a canary deployment @@ -115,13 +115,13 @@ Here's an example setup flow from scratch: #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight within your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), +You can change the traffic weight in your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). To use your [deploy board](../../user/project/deploy_boards.md): -1. Navigate to **Deployments > Environments** for your project. -1. Set the new weight with the dropdown on the right side. +1. Go to **Deployments > Environments** for your project. +1. Set the new weight with the dropdown list on the right side. 1. Confirm your selection. Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index e14a71a7e10..82106c9d1a9 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.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/8) in GitLab 14.5. WARNING: -This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) +This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic @@ -19,11 +19,11 @@ Kubernetes Service (EKS). ## Connect an existing EKS cluster If you already have an EKS cluster and want to connect it to GitLab, -use the [GitLab Agent](../../clusters/agent/index.md). +use the [GitLab agent](../../clusters/agent/index.md). ## Create a new EKS cluster -To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). +To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 0c3827bcbb1..f2d537513b7 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/index.md) instead. If you have an existing Kubernetes cluster, you can add it to a project, group, @@ -69,8 +69,8 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. 1. **Menu > Admin > Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. -1. Click the **Add existing cluster** tab and fill in the details: +1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown menu. +1. On the **Connect a cluster** page, fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. 1. **Environment scope** (required) - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 99edddeb3e9..cb8d04e0e28 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -19,7 +19,7 @@ hosted on Google Kubernetes Engine (GKE). ## Connect an existing GKE cluster If you already have a GKE cluster and want to connect it to GitLab, -use the [GitLab Agent](../../clusters/agent/index.md). +use the [GitLab agent](../../clusters/agent/index.md). ## Create a new GKE cluster from GitLab diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index a0fca517f2e..a4f6dc325c8 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). +To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -29,7 +29,7 @@ in a few clicks. > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) to **safely create new clusters from GitLab**. Creating clusters from GitLab using cluster certificates is still available on the @@ -49,7 +49,7 @@ supports connecting existing clusters using the certificate-based connection met ## Add existing cluster -As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab agent](../../clusters/agent/index.md) to connect your cluster to GitLab. Alternatively, you can [add an existing cluster](add_existing_cluster.md) @@ -57,7 +57,7 @@ through the certificate-based method, but we don't recommend using this method f ## Configure your cluster -As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab agent](../../clusters/agent/index.md) to configure your cluster. ## Disable a cluster diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 4e00ae0dd07..8ff0a275649 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/index.md) instead. When creating a cluster in GitLab, you are asked if you would like to create either: diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index e89ce12b35e..c1cdf754c11 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). -To deploy with the Agent, use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md). +To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/index.md). +To deploy with the agent, use the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). A Kubernetes cluster can be the destination for a deployment job. If @@ -143,6 +143,6 @@ Reasons for failure include: NOTE: Project-level clusters upgraded from GitLab 12.0 or older may be configured -in a way that causes this error. Ensure you deselect the +in a way that causes this error. Ensure you clear the [GitLab-managed cluster](gitlab_managed_clusters.md) option if you want to manage namespaces and service accounts yourself. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 686b3026b2c..9c5cc14f720 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). +To connect your cluster to GitLab, use the [GitLab agent](../../../user/clusters/agent/index.md). To manage applications, use the [Cluster Project Management Template](../../../user/clusters/management_project_template.md). You can choose to allow GitLab to manage your cluster for you. If your cluster diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index dc37060593c..f89d863e83b 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, use the -[GitLab Agent](../../clusters/agent/index.md). +[GitLab agent](../../clusters/agent/index.md). [Project-level](../../infrastructure/clusters/connect/index.md#cluster-levels-deprecated) Kubernetes clusters allow you to connect a Kubernetes cluster to a project in GitLab. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index a56eaa9b953..149df5248c8 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Using multiple Kubernetes clusters for a single project **with cluster certificates** was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect clusters to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab agent](../../../user/clusters/agent/index.md). You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, 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 a0297a7a86f..f6f31ee8f36 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +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 --- # Container Host Security **(FREE)** 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 4e56b7e5140..25e2f6ddb91 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 @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +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 --- # Getting started with Container Host Security **(FREE)** 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 7176a1cf1b9..eeaf7e82ef4 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +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 --- # Container Network Security **(FREE)** 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 e6c91302d7b..43f4ea6c326 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 @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +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 --- # Getting started with Container Network Security **(FREE)** diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index 473195f4c17..3a80132fb50 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -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/#designated-technical-writers +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 --- # Protecting your deployed applications **(FREE)** diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index eb18834cc6b..fefc27063a6 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -124,7 +124,7 @@ Only one CODEOWNERS pattern can match per file path. ### Organize Code Owners by putting them into sections -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. You can organize Code Owners by putting them into named sections. @@ -170,7 +170,7 @@ entries under **Database**. The entries defined under the sections **Documentati ### Make a Code Owners section optional -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. You can designate optional sections in your Code Owners file. Prepend the section name with the caret `^` character to treat the entire section as optional. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 15490ab0b94..567c15c7d5f 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -7,8 +7,8 @@ type: howto, reference # Deploy boards (DEPRECATED) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in GitLab 9.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. > - In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as > duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) > in GitLab 13.6. @@ -20,7 +20,7 @@ type: howto, reference WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493) -to add this functionality to the [Agent](../index.md). +to add this functionality to the [agent](../index.md). GitLab deploy boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status diff --git a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png b/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png Binary files differdeleted file mode 100644 index 2f708555af1..00000000000 --- a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png +++ /dev/null diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 57f6efa3092..b7674be2fa0 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -2,186 +2,145 @@ stage: Release group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto, reference --- # Deploy keys **(FREE)** -Deploy keys allow read-only or read-write access to your -repositories by importing an SSH public key into your GitLab instance. +Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys +to access a repository from an external host, like a build server or Continuous Integration (CI) server. -Deploy keys streamline interactions between your GitLab repository and another -machine. For example, setting up a deploy key allows secure cloning of your -repositories to a Continuous Integration (CI) server without setting up a fake -user account. +Depending on your needs, you might want to use a [deploy token](../deploy_tokens/) to access a repository instead. -There are two types of deploy keys: +| Attribute | Deploy key | Deploy token | +|------------------|-------------|--------------| +| Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. | +| Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | +| Validity | Valid as long as it's registered and enabled. | Can be given an expiration date. | +| Registry access | Cannot access a package registry. | Can read from and write to a package registry. | -- [Project deploy keys](#project-deploy-keys) -- [Public deploy keys](#public-deploy-keys) +## Scope -## Key details on deploy keys +A deploy key has a defined scope when it is created: -Deploy keys allow a remote machine (VM, physical, and so on) to access a GitLab -repository with just a few steps. If you want a remote machine to interact with a GitLab -repository in automation, it's a simple solution. +- **Project deploy key:** Access is limited to the selected project. +- **Public deploy key:** Access can be granted to _any_ project in a GitLab instance. Access to each + project must be [granted](#grant-project-access-to-a-public-deploy-key) by a user with at least + the Maintainer role. -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 -in the GitLab project. +You cannot change a deploy key's scope after creating it. -If this security implication is a concern for your organization, -[Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more -security control. +## Permissions -## Deploy keys permissions +A deploy key is given a permission level when it is created: -You can choose the access level of a deploy key when you enable it on a project: +- **Read-only:** A read-only deploy key can only read from the repository. +- **Read-write:** A read-write deploy key can read from, and write to, the repository. -- `read-only`: The deploy key can read a repository. -- `read-write`: The deploy key can read a repository and write to it. +You can change a deploy key's permission level after creating it. Changing a project deploy key's +permissions only applies for the current project. -Project maintainers and owners can activate and deactivate deploy keys. -They can also add their own deploy keys and enable them for this project. +When a read-write deploy key is used to push a commit, GitLab checks if the creator of the +deploy key has permission to access the resource. -When a `write-access` deploy key is used to push a commit, GitLab checks if -the **creator** of the deploy key has permission to access the resource. For example: +For example: - When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), - the **creator** of the deploy key must have access to the branch. -- When a deploy key is used to push a commit that triggers a CI/CD pipelines, the **creator** of - the deploy key must have access to the CI/CD resources (like protected environments, secret variables, and so on). -- If the **creator** of a deploy key does not have permissions to read a project's - repository, the deploy key _might_ encounter an error during the process. + the _creator_ of the deploy key must have access to the branch. +- When a deploy key is used to push a commit that triggers a CI/CD pipeline, the _creator_ of the + deploy key must have access to the CI/CD resources, including protected environments and secret + variables. -## Differences between deploy keys and deploy tokens +## View deploy keys -Both deploy keys and [deploy tokens](../deploy_tokens/index.md#deploy-tokens) can -help you access a repository, but there are some notables differences between them: - -- Deploy keys are shareable between projects that are not related or don't even - belong to the same group. Deploy tokens belong to either a project or - [a group](../deploy_tokens/index.md#group-deploy-token). -- A deploy key is an SSH key you generate on the **remote machine**. A deploy - token, on the other hand, is generated by your **GitLab instance**, and is - provided to users only once (at creation time). -- A deploy key is valid as long as it's registered and enabled. Deploy tokens - can be time-sensitive, as you can control their validity by setting an - expiration date to them. -- You can't log in to a registry with deploy keys, or perform read / write operations - on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). -- You need an SSH key pair to use deploy keys, but not deploy tokens. - -## How to enable deploy keys - -### Project deploy keys - -[Project maintainers and owners](../../permissions.md#project-members-permissions) -can add or enable a deploy key for a project repository: +To view the deploy keys available 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 **Deploy keys**. -1. Specify a title for the new deploy key and paste your public SSH key. -1. Optional. To allow `read-write` access, select the **Grant write permissions to this key** checkbox. Leave it unchecked for `read-only` access. -There are three lists of project deploy keys: +The deploy keys available are listed: -- Enabled deploy keys -- Privately accessible deploy keys -- Public accessible deploy keys +- **Enabled deploy keys:** Deploy keys that have access to the project. +- **Privately accessible deploy keys:** Project deploy keys that don't have access to the project. +- **Public accessible deploy keys:** Public deploy keys that don't have access to the project. - +## Create a project deploy key -After you add a key, it's enabled for this project by default and it appears -in the **Enabled deploy keys** tab. +Prerequisites: -In the **Privately accessible deploy keys** tab, you can enable a private key which -has been already imported in a different project. If you have access to these keys, -it's because you have either: +- You must have at least the Maintainer role for the project. +- [Generate an SSH key pair](../../../ssh/index.md#generate-an-ssh-key-pair). Put the private SSH + key on the host that requires access to the repository. -- Previously uploaded the keys yourself in a different project. -- You are a maintainer or owner of the other project where the keys were imported. - -In the **Publicly accessible deploy keys** tab, you can enable -keys that were [made available to your entire GitLab instance](#public-deploy-keys). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy keys**. +1. Complete the fields. +1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** + checkbox. -After a key is added, you can edit it to update its title, or switch between `read-only` -and `read-write` access. +A project deploy key is enabled when it is created. You can modify only a project deploy key's +name and permissions. -NOTE: -If you have enabled a privately or publicly accessible or deploy key for your -project, and if you then update the access level for this key from `read-only` to -`read-write`, the change is only for the **current project**. +## Create a public deploy key -### Public deploy keys +Prerequisites: -Public deploy keys allow `read-only` or `read-write` access to any repository in -your GitLab instance. This allows for the integration of your repositories to -secure, shared services, such as CI/CD. +- You must have administrator access. +- [Generate an SSH key pair](../../../ssh/index.md#generate-an-ssh-key-pair). Put the private SSH + key on the host that requires access to the repository. -Instance administrators can add public deploy keys: +To create a public deploy key: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. +1. Complete the fields. + - Use a meaningful description for **Name**. For example, include the name of the external host + or application that will use the public deploy key. -Make sure your new key has a meaningful title. This title is the primary -way for project maintainers and owners to identify the correct public deploy key -to add to a repository or project. For example, the key you set up might be -intended to give access to a SaaS CI/CD instance. In this case use the name of -that service in the key title if that is all the key is used for. +You can modify only a public deploy key's name. - +## Grant project access to a public deploy key -After adding a key, it's available to any shared system. Users with a maintainer role or -higher can [authorize a public deploy key](#project-deploy-keys) to start using -it with the project. +Prerequisites: -NOTE: -The **Publicly accessible deploy keys** tab in a Project's CI/CD -settings only appears if there is at least one Public deploy key configured. +- You must have at least the Maintainer role for the project. -Public deploy keys can provide greater security compared to project deploy keys. -This is because the administrator of the target integrated system is the only -entity who needs to know or configure the key value. +To grant a public deploy key access to a project: -When creating a Public deploy key, consider what scope and permissions are -required for it across the entire GitLab instance. For very narrow usage, such -as a single specific service, a `read-only` deploy key tied to this service is -best. If the service entails broader usage across the instance, a -deploy key with full `read-write` access is more appropriate. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy keys**. +1. Select **Publicly accessible deploy keys**. +1. In the key's row, select **Enable**. +1. To grant read-write permission to the public deploy key: + 1. In the key's row, select **Edit** (**{pencil}**). + 1. Select the **Grant write permissions to this key** checkbox. + +## Revoke project access of a deploy key -WARNING: -Adding a public deploy key **does not** immediately expose any repository -to the remote machine. Access to a project is only given when a project -maintainer chooses to make use of a deploy key in the project's -configuration. +To revoke a deploy key's access to a project, you can disable it. Any service that relies on +a deploy key stops working when the key is disabled. -## How to disable deploy keys +Prerequisites: -[Project maintainers and owners](../../permissions.md#project-members-permissions) -can remove or disable a deploy key for a project repository: +- You must have at least the Maintainer role for the project. + +To disable a deploy key: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). -NOTE: -Any service that relies on a deploy key stops working after that key is removed. - -If the key is **publicly accessible**, it is removed from the project, but can -still be found under **Publicly accessible deploy keys**. - -If the key is **privately accessible** and only in use by this project, it is -deleted entirely from GitLab on removal. +What happens to the deploy key when it is disabled depends on the following: -If the key is **privately accessible** and also in use by other projects, it is -removed from the project, but still available under **Privately accessible -deploy keys**. +- If the key is publicly accessible, it is removed from the project but still available in the + **Publicly accessible deploy keys** tab. +- If the key is privately accessible and only in use by this project, it is deleted. +- If the key is privately accessible and also in use by other projects, it is removed from the + project, but still available in the **Privately accessible deploy keys** tab. ## Troubleshooting @@ -192,7 +151,7 @@ branch](../protected_branches.md). - The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. -- **No one** is selected in [the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) of the protected branch. +- **No one** is selected in [the **Allowed to push** section](../protected_branches.md#configure-a-protected-branch) of the protected branch. All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 9911c90863d..4810fb96ed3 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -25,10 +25,10 @@ GitLab supports two different modes of file locking: - [Exclusive file locks](#exclusive-file-locks) for binary files: done **through the command line** with Git LFS and `.gitattributes`, it prevents locked - files from being modified on any branch. **(FREE)** + files from being modified on any branch. - [Default branch locks](#default-branch-file-and-directory-locks): done **through the GitLab UI**, it prevents locked files and directories being - modified on the default branch. **(PREMIUM)** + modified on the default branch. ## Permissions @@ -40,7 +40,7 @@ users are prevented from modifying locked files by pushing, merging, or any other means, and are shown an error like: `The path '.gitignore' is locked by Administrator`. -## Exclusive file locks **(FREE)** +## Exclusive file locks This process allows you to lock single files or file extensions and it is done through the command line. It doesn't require GitLab paid subscriptions. @@ -192,7 +192,7 @@ Suggested workflow for shared projects: ## Default branch file and directory locks **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab 8.9. This process allows you to lock one file at a time through the GitLab UI and requires access to [GitLab Premium](https://about.gitlab.com/pricing/) diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 728f51a8062..ef0c787b9d3 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -7,61 +7,67 @@ type: reference # Syntax Highlighting **(FREE)** -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the +[Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language +to use based on the file extension, which most of the time is sufficient. + +The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. -<!-- vale gitlab.Spelling = NO --> - -If GitLab is guessing wrong, you can override its choice of language using the -`gitlab-language` attribute in `.gitattributes`. For example, if you are working in a Prolog -project and using the `.pl` file extension (which would normally be highlighted as Perl), -you can add the following to your `.gitattributes` file: +## Override syntax highlighting for a file type -<!-- vale gitlab.Spelling = YES --> - -``` conf -*.pl gitlab-language=prolog -``` +NOTE: +The Web IDE [does not support `.gitattribute` files](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). -<!-- vale gitlab.Spelling = NO --> +To override syntax highlighting for a file type: -When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. +1. If a `.gitattributes` file does not exist in the root directory of your project, + create a blank file with this name. +1. For each file type you want to modify, add a line to the `.gitattributes` file + declaring the file extension and your desired highlighting language: -<!-- vale gitlab.Spelling = YES --> + ```conf + # This extension would normally receive Perl syntax highlighting + # but if we also use Prolog, we may want to override highlighting for + # files with this extension: + *.pl gitlab-language=prolog + ``` -The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +1. Commit, push, and merge your changes into your default branch. -``` conf -/Nicefile gitlab-language=ruby -``` +After the changes merge into your [default branch](repository/branches/default.md), +all `*.pl` files in your project are highlighted in your preferred language. -To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through common gateway interface (CGI) options, such as: +You can also extend the highlighting with common gateway interface (CGI) options, such as: ``` conf -# json with erb in it +# JSON file with .erb in it /my-cool-file gitlab-language=erb?parent=json -# an entire file of highlighting errors! +# An entire file of highlighting errors! /other-file gitlab-language=text?token=Error ``` -These configurations only take effect when the `.gitattributes` -file is in your [default branch](repository/branches/default.md). +## Disable syntax highlighting for a file type -NOTE: -The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). +To disable highlighting entirely for a file type, follow the instructions for overriding +the highlighting for a file type, and use `gitlab-language=text`: -## Configure maximum file size for highlighting +```conf +# Disable syntax highlighting for this file type +*.module gitlab-language=text +``` -You can configure the maximum size of the file to be highlighted. +## Configure maximum file size for highlighting -The file size is measured in kilobytes, and is set to a default of `512 KB`. Any file _over_ the file size is rendered in plain text. +By default, GitLab renders any file larger than 512 KB in plain text. To change this value: -1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) configuration file. +1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) + configuration file for your project. 1. Add this section, replacing `maximum_text_highlight_size_kilobytes` with the value you want. @@ -72,3 +78,5 @@ The file size is measured in kilobytes, and is set to a default of `512 KB`. Any ## https://docs.gitlab.com/ee/user/project/highlighting.html maximum_text_highlight_size_kilobytes: 512 ``` + +1. Commit, push, and merge your changes into your default branch. diff --git a/doc/user/project/img/labels_sort_label_priority.png b/doc/user/project/img/labels_sort_label_priority.png Binary files differdeleted file mode 100644 index faf629ac61d..00000000000 --- a/doc/user/project/img/labels_sort_label_priority.png +++ /dev/null diff --git a/doc/user/project/img/labels_sort_priority.png b/doc/user/project/img/labels_sort_priority.png Binary files differdeleted file mode 100644 index a6b5fca26f4..00000000000 --- a/doc/user/project/img/labels_sort_priority.png +++ /dev/null diff --git a/doc/user/project/img/labels_subscriptions_v13_5.png b/doc/user/project/img/labels_subscriptions_v13_5.png Binary files differdeleted file mode 100644 index a2a4e9e50cc..00000000000 --- a/doc/user/project/img/labels_subscriptions_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 62495872659..8c0d9fc422b 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from Bitbucket Cloud to GitLab **(FREE)** NOTE: -The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket +The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket Server (aka Stash). If you are trying to import projects from Bitbucket Server, use [the Bitbucket Server importer](bitbucket_server.md). @@ -31,25 +31,37 @@ When importing: - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Requirements +## Prerequisite for GitLab self-managed To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) -must be enabled. Ask your GitLab administrator to enable this if it isn't already enabled. +must be enabled. If it isn't enabled, ask your GitLab administrator to enable it. By default it's +enabled on GitLab.com. ## How it works -When issues/pull requests are being imported, the Bitbucket importer tries to find -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 -(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. +When issues/pull requests are being imported, the Bitbucket importer uses the Bitbucket nickname of +the author/assignee and tries to find the same Bitbucket identity in GitLab. If they don't match or +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. The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's namespace that started the import process. +## Requirements for user-mapped contributions + +For user contributions to be mapped, each user must complete the following before the project import: + +1. Verify that the username in the [Bitbucket account settings](https://bitbucket.org/account/settings/) + matches the public name in the [Atlassian account settings](https://id.atlassian.com/manage-profile/profile-and-visibility). + If they don't match, modify the public name in the Atlassian account settings to match the + username in the Bitbucket account settings. + +1. Connect your Bitbucket account in [GitLab profile social sign-in](https://gitlab.com/-/profile/account). + +1. [Set your public email](../../profile/index.md#set-your-public-email). + ## Import your Bitbucket repositories 1. Sign in to GitLab. @@ -69,9 +81,35 @@ namespace that started the import process. ## Troubleshooting -If you have more than one Bitbucket account, be sure to sign in to the correct account. +### If you have more than one Bitbucket account + +Be sure to sign in to the correct account. + If you've accidentally started the import process with the wrong account, follow these steps: 1. Revoke GitLab access to your Bitbucket account, essentially reversing the process in the following procedure: [Import your Bitbucket repositories](#import-your-bitbucket-repositories). 1. Sign out of the Bitbucket account. Follow the procedure linked from the previous step. + +### User mapping fails despite matching names + +[For user mapping to work](#requirements-for-user-mapped-contributions), +the username in the Bitbucket account settings must match the public name in the Atlassian account +settings. If these names match but user mapping still fails, the user may have modified their +Bitbucket username after connecting their Bitbucket account in the +[GitLab profile social sign-in](https://gitlab.com/-/profile/account). + +To fix this, the user must verify that their Bitbucket external UID in the GitLab database matches their +current Bitbucket public name, and reconnect if there's a mismatch: + +1. [Use the API to get the currently authenticated user](../../../api/users.md#list-current-user-for-normal-users). + +1. In the API's response, the `identities` attribute contains the Bitbucket account that exists in + the GitLab database. If the `extern_uid` doesn't match the current Bitbucket public name, the + user should reconnect their Bitbucket account in the [GitLab profile social sign-in](https://gitlab.com/-/profile/account). + +1. Following reconnection, the user should use the API again to verify that their `extern_uid` in + the GitLab database now matches their current Bitbucket public name. + +The importer must then [delete the imported project](../../project/working_with_projects.md#delete-a-project) +and import again. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 120c64e00f2..867477c83b2 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -51,4 +51,4 @@ are some useful links to get you started: - [ClearCase to Git](https://therub.org/2013/07/19/clearcase-to-git/) - [Dual syncing ClearCase to Git](https://therub.org/2013/10/22/dual-syncing-clearcase-and-git/) - [Moving to Git from ClearCase](https://sateeshkumarb.wordpress.com/2011/01/15/moving-to-git-from-clearcase/) -- [ClearCase to Git webinar](https://www.brighttalk.com/webcast/11817/162473/clearcase-to-git) +- [ClearCase to Git webinar](https://www.brighttalk.com/webcast/11817/162473) diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 55c5feff1f0..8bb716d8122 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -71,6 +71,6 @@ Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) - [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) -- [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) +- [Convert a CVS repository to Git](http://www.techrepublic.com/article/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index bcbc6e09f1b..6913cda0cd5 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -14,7 +14,7 @@ mind that it is possible only if GitLab.com integration is enabled on your GitLa To get to the importer page you need to go to "New project" page. NOTE: -If you are interested in importing Wiki and Merge Request data to your new instance, +If you are interested in importing Wiki and merge request data to your new instance, you'll need to follow the instructions for [exporting a project](../settings/import_export.md#export-a-project-and-its-data)  diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 5f7475eac36..a44669e738e 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -32,8 +32,7 @@ imported into the GitLab issue's description as plain text. Our parser for converting text in Jira issues to GitLab Flavored Markdown is only compatible with Jira V3 REST API. -There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of -items, such as issue assignees, comments, and much more. These are included in the future +There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of issue assignees, comments, and much more in the future iterations of the GitLab Jira importer. ## Prerequisites @@ -60,7 +59,7 @@ Importing large projects may take several minutes depending on the size of the i To import Jira issues to a GitLab project: -1. On the **{issues}** **Issues** page, click **Import Issues** (**{import}**) **> Import from Jira**. +1. On the **{issues}** **Issues** page, select **Import Issues** (**{import}**) **> Import from Jira**.  @@ -68,20 +67,20 @@ To import Jira issues to a GitLab project: The following form appears. If you've previously set up the [Jira integration](../../../integration/jira/index.md), you can now see - the Jira projects that you have access to in the dropdown. + the Jira projects that you have access to in the dropdown list.  -1. Click the **Import from** dropdown and select the Jira project that you wish to import issues from. +1. Click the **Import from** dropdown list and select the Jira project that you wish to import issues from. In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira users are mapped. - When the form appears, the dropdown defaults to the user conducting the import. + When the form appears, the dropdown list defaults to the user conducting the import. -1. To change any of the mappings, click the dropdown in the **GitLab username** column and +1. To change any of the mappings, click the dropdown list in the **GitLab username** column and select the user you want to map to each Jira user. - The dropdown may not show all the users, so use the search bar to find a specific + The dropdown list may not show all the users, so use the search bar to find a specific user in this GitLab project. 1. Click **Continue**. You're presented with a confirmation that import has started. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index d155f91e40b..71ca9f4f640 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md) with GitLab. If your preferred issue tracker is not listed in the -[integrations list](../../../integration/external-issue-tracker.md#integration), +[integrations list](../../../integration/external-issue-tracker.md#configure-an-external-issue-tracker), you can enable a custom issue tracker. After you enable the custom issue tracker, a link to the issue tracker displays diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 0a685ad0efb..7e8de776619 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -32,15 +32,15 @@ where you can select a project to enable the GitLab Slack application for. Alternatively, you can configure the Slack application with a project's integration settings. -Keep in mind that you need to have the appropriate permissions for your Slack -team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). +Keep in mind that you must have the appropriate permissions for your Slack +team to be able to install a new application, read more in Slack's +documentation on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). To enable the GitLab service for your Slack team: 1. Go to your project's **Settings > Integration > Slack application** (only visible on GitLab.com). -1. Click **Add to Slack**. +1. Select **Add to Slack**. That's all! You can now start using the Slack slash commands. @@ -49,11 +49,11 @@ That's all! You can now start using the Slack slash commands. To create a project alias on GitLab.com for Slack integration: 1. Go to your project's home page. -1. Navigate to **Settings > Integrations** (only visible on GitLab.com) -1. On the **Integrations** page, click **Slack application**. +1. Go to **Settings > Integrations** (only visible on GitLab.com) +1. On the **Integrations** page, select **Slack application**. 1. The current **Project Alias**, if any, is displayed. To edit this value, - click **Edit**. -1. Enter your desired alias, and click **Save changes**. + select **Edit**. +1. Enter your desired alias, and select **Save changes**. Some Slack commands require a project alias, and fail with the following error if the project alias is incorrect or missing from the command: diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md new file mode 100644 index 00000000000..d66e2222538 --- /dev/null +++ b/doc/user/project/integrations/harbor.md @@ -0,0 +1,50 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Harbor container registry integration **(FREE)** + +Use Harbor as the container registry for your GitLab project. + +[Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud native compute platforms, like Kubernetes and Docker. + +This integration can help you if you need GitLab CI/CD and a container image repository. + +## Prerequisites + +In the Harbor instance, ensure that: + +- The project to be integrated has been created. +- The signed-in user has permission to pull, push, and edit images in the Harbor project. + +## Configure GitLab + +GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Harbor**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the Harbor configuration information: + - **Harbor URL**: The base URL of Harbor instance which is being linked to this GitLab project. For example, `https://harbor.example.net`. + - **Harbor project name**: The project name in the Harbor instance. For example, `testproject`. + - **Username**: Your username in the Harbor instance, which should meet the requirements in [prerequisites](#prerequisites). + - **Password**: Password of your username. + +1. Select **Save changes**. + +After the Harbor integration is activated: + +- The global variables `$HARBOR_USER`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. +- The project-level integration settings override the group-level integration settings. + +## Secure your requests to the Harbor APIs + +For each API request through the Harbor integration, the credentials for your connection to the Harbor API use +the `username:password` combination. The following are suggestions for safe use: + +- Use TLS on the Harbor APIs you connect to. +- Follow the principle of least privilege (for access on Harbor) with your credentials. +- Have a rotation policy on your credentials. diff --git a/doc/user/project/integrations/img/failed_badges.png b/doc/user/project/integrations/img/failed_badges.png Binary files differnew file mode 100644 index 00000000000..d44415a8687 --- /dev/null +++ b/doc/user/project/integrations/img/failed_badges.png diff --git a/doc/user/project/integrations/img/failed_banner.png b/doc/user/project/integrations/img/failed_banner.png Binary files differnew file mode 100644 index 00000000000..ba40c1301d6 --- /dev/null +++ b/doc/user/project/integrations/img/failed_banner.png diff --git a/doc/user/project/integrations/img/failed_banner_error.png b/doc/user/project/integrations/img/failed_banner_error.png Binary files differnew file mode 100644 index 00000000000..8f4dabbf8c2 --- /dev/null +++ b/doc/user/project/integrations/img/failed_banner_error.png diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index b317e65bdf2..768acb02ee6 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -32,7 +32,7 @@ on your configuration: If Mattermost is installed on the same server as GitLab, the configuration process can be done for you by GitLab. -Go to the Mattermost Slash Command service on your project and click **Add to Mattermost** button. +Go to the Mattermost Slash Command service on your project and select **Add to Mattermost**. ## Manual configuration @@ -52,13 +52,13 @@ installations from source. To enable custom slash commands from the Mattermost administrator console: 1. Sign in to Mattermost as a user with administrator privileges. -1. Next to your username, click the **{ellipsis_v}** **Settings** icon, and +1. Next to your username, select the **{ellipsis_v}** **Settings** icon, and select **System Console**. 1. Select **Integration Management**, and set these values to `TRUE`: - **Enable Custom Slash Commands** - **Enable integrations to override usernames** - **Enable integrations to override profile picture icons** -1. Click **Save**, but do not close this browser tab, because you need it in +1. Select **Save**, but do not close this browser tab, because you need it in a later step. ### Get configuration values from GitLab @@ -85,9 +85,9 @@ the previous step: 1. In the Mattermost tab you left open when you [enabled custom slash commands](#enable-custom-slash-commands), go to your team page. -1. Click the **{ellipsis_v}** **Settings** icon, and select **Integrations**. +1. Select the **{ellipsis_v}** **Settings** icon, and select **Integrations**. 1. In the left menu, select **Slash commands**. -1. Click **Add Slash Command**: +1. Select **Add Slash Command**:  1. Provide a **Display Name** and **Description** for your new command. @@ -101,7 +101,7 @@ the previous step: [viewed configuration values](#get-configuration-values-from-gitlab). 1. For all other values, you may use the suggestions from GitLab or use your preferred values. -1. Copy the **Token** value, as you need it in a later step, and click **Done**. +1. Copy the **Token** value, as you need it in a later step, and select **Done**. ### Provide the Mattermost token to GitLab @@ -116,7 +116,7 @@ provide to GitLab:  -1. Click **Save changes** for the changes to take effect. +1. Select **Save changes** for the changes to take effect. Your slash command can now communicate with your GitLab project. @@ -165,4 +165,4 @@ different types of notifications. All events are sent to the specified channel. ## Further reading - [Mattermost slash commands documentation](https://docs.mattermost.com/developer/slash-commands.html) -- [Omnibus GitLab Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/) +- [Omnibus GitLab Mattermost](../../../integration/mattermost/) diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 8ecc16050be..2cb62b8924e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -43,6 +43,7 @@ Click on the service links to see further configuration instructions and details | [Flowdock](../../../api/integrations.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | | [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat.| **{dotted-circle}** No | +| [Harbor](harbor.md) | Use Harbor as the container registry. | **{dotted-circle}** No | | [irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | | [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | | JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 9d8b98edba1..d37196ec114 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -202,6 +202,10 @@ The available values for `object_attributes.action` in the payload are: The `assignee` and `assignee_id` keys are deprecated and contain the first assignee only. +The `escalation_status` and `escalation_policy` fields are +only available for issue types which support escalations, +such as incidents. + Request header: ```plaintext @@ -271,6 +275,12 @@ Payload example: "url": "http://example.com/diaspora/issues/23", "state": "opened", "action": "open", + "severity": "high", + "escalation_status": "triggered", + "escalation_policy": { + "id": 18, + "name": "Engineering On-call" + }, "labels": [{ "id": 206, "title": "API", @@ -771,7 +781,8 @@ Payload example: Merge request events are triggered when: - A new merge request is created. -- An existing merge request is updated, approved, unapproved, merged, or closed. +- An existing merge request is updated, approved (by all required approvers), unapproved, merged, or closed. +- An individual user adds or removes their approval to an existing merge request. - A commit is added in the source branch. - All threads are resolved on the merge request. @@ -783,6 +794,8 @@ The available values for `object_attributes.action` in the payload are: - `update` - `approved` - `unapproved` +- `approval` +- `unapproval` - `merge` Request header: @@ -1294,7 +1307,7 @@ Payload example: "id": 3, "name": "User", "email": "user@gitlab.com", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" }, "commit": { "id": 2366, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index ace5783c852..e823391401d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -62,7 +62,8 @@ You can configure a webhook for a group or a project. ## Test a webhook -You can trigger a webhook manually, to ensure it's working properly. +You can trigger a webhook manually, to ensure it's working properly. You can also send +a test request to re-enable a [disabled webhook](#re-enable-disabled-webhooks). For example, to test `push events`, your project should have at least one commit. The webhook uses this commit in the webhook. @@ -72,6 +73,8 @@ To test a webhook: 1. Scroll down to the list of configured webhooks. 1. From the **Test** dropdown list, select the type of event to test. +You can also test a webhook from its edit page. +  ## Create an example webhook receiver @@ -143,7 +146,32 @@ GitLab webhooks, keep in mind the following: GitLab assumes the hook failed and retries it. Most HTTP libraries take care of the response for you automatically but if you are writing a low-level hook, this is important to remember. -- GitLab ignores the HTTP status code returned by your endpoint. +- GitLab usually ignores the HTTP status code returned by your endpoint, + unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). + +### Failing webhooks + +> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. + +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 `web_hooks_disable_failed`. +The feature is not ready for production use. + +If a webhook fails repeatedly, it may be disabled automatically. + +Webhooks that return response codes in the `5xx` range are understood to be failing +intermittently, and are temporarily disabled. This lasts initially +for 10 minutes. If the hook continues to fail, the back-off period is +extended on each retry, up to a maximum disabled period of 24 hours. + +Webhooks that return failure codes in the `4xx` range are understood to be +misconfigured, and these are disabled until you manually re-enable +them. These webhooks are not automatically retried. + +See [troubleshooting](#troubleshoot-webhooks) for information on +how to see if a webhook is disabled, and how to re-enable it. ## How image URLs are displayed in the webhook body @@ -186,6 +214,13 @@ To view the table: 1. In your project, on the left sidebar, select **Settings > Webhooks**. 1. Scroll down to the webhooks. +1. Each [failing webhook](#failing-webhooks) has a badge listing it as: + + - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. + - **Fails to connect** if it is temporarily disabled and will retry later. + +  + 1. Select **Edit** for the webhook you want to view. The table includes the following details about each request: @@ -216,8 +251,8 @@ If the endpoint doesn't send an HTTP response in those 10 seconds, GitLab may assume the webhook failed and retry it. If your webhooks are failing or you are receiving multiple requests, -you can try changing the default timeout value. -In your `/etc/gitlab/gitlab.rb` file, uncomment or add the following setting: +an administrator can try changing the default timeout value +by uncommenting or adding the following setting in `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['webhook_timeout'] = 10 @@ -233,3 +268,17 @@ determined by [CAcert.org](http://www.cacert.org/). If that is not the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. Missing intermediate certificates are common causes of verification failure. + +### Re-enable disabled webhooks + +If a webhook is failing, a banner displays at the top of the edit page explaining +why it is disabled, and when it will be automatically re-enabled. For example: + + + +In the case of a failed webhook, an error banner is displayed: + + + +To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test +request succeeds, the webhook is re-enabled. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 71440298d85..d731ceb5aca 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -53,7 +53,7 @@ the issue board feature. > - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. > - Multiple issue boards per group are available in GitLab Premium. -Multiple issue boards allow for more than one issue board for a given project **(FREE)** or group **(PREMIUM)**. +Multiple issue boards allow for more than one issue board for a given project in GitLab Free or group in GitLab Premium and higher tiers. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -275,7 +275,7 @@ Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in GitLab 11.0. As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. @@ -295,7 +295,7 @@ To remove an assignee list, just as with a label list, click the trash icon. ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in GitLab 11.2. You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. To add a milestone list: @@ -333,7 +333,7 @@ to and from a iteration list to manipulate the iteration of the dragged issues. ### Group issues in swimlanes **(PREMIUM)** -> - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in GitLab 13.6. > - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. > - Editing iteration in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290232) in GitLab 13.9. @@ -356,7 +356,7 @@ appears on the right. There you can see and edit the issue's: - Title - Assignees -- Epic **(PREMIUM)** +- [Epic](../group/epics/index.md) - Milestone - Time tracking value (view only) - Due date @@ -506,14 +506,14 @@ You can filter by the following: - Assignee - Author -- Epic -- Iteration +- [Epic](../group/epics/index.md) +- [Iteration](../group/iterations/index.md) - Label - Milestone - My Reaction - Release - Type (issue/incident) -- Weight +- [Weight](issues/issue_weight.md) #### Filtering issues in a group board @@ -536,7 +536,7 @@ changing a label. A typical workflow of using an issue board would be: -1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority) +1. You [create](labels.md#create-a-label) and [prioritize](labels.md#set-label-priority) labels to categorize your issues. 1. You have a bunch of issues (ideally labeled). 1. You visit the issue board and start [creating lists](#create-a-new-list) to diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 947fbdcc2d1..e5d698fa97a 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -52,7 +52,7 @@ export, after which the email is prepared. ## Sorting -Exported issues are always sorted by `Issue ID`. +Exported issues are always sorted by `Title`. ## Format @@ -63,11 +63,11 @@ the values: | Column | Description | |------------------------------------------|-----------------------------------------------------------| +| Title | Issue `title` | +| Description | Issue `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 | @@ -85,6 +85,10 @@ the values: | [Epic](../../group/epics/index.md) ID | ID of the parent epic, introduced in 12.7 | | [Epic](../../group/epics/index.md) Title | Title of the parent epic, introduced in 12.7 | +In GitLab 14.7 and earlier, the first two columns were `Issue ID` and `URL`, +which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) +when importing back into GitLab. + ## Limitations - Export Issues to CSV is not available at the Group's Issues List. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 66ca29c094e..e9f3f4be1c3 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -6,4 +6,6 @@ remove_date: '2022-02-24' This file was moved to [another location](index.md). <!-- This redirect file can be deleted after <2022-02-24>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 155d6260a5c..58591129d97 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -19,7 +19,7 @@ You can create an issue in many ways in GitLab: - [From a project](#from-a-project) - [From a group](#from-a-group) -- [From another issue](#from-another-issue) +- [From another issue or incident](#from-another-issue-or-incident) - [From an issue board](#from-an-issue-board) - [By sending an email](#by-sending-an-email) - [Using a URL with prefilled values](#using-a-url-with-prefilled-values) @@ -70,9 +70,10 @@ The newly created issue opens. The project you selected most recently becomes the default for your next visit. This can save you a lot of time and clicks, if you mostly create issues for the same project. -### From another issue +### From another issue or incident -> New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. +> - New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. +> - **Relate to…** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. You can create a new issue from an existing one. The two issues can then be marked as related. @@ -83,10 +84,10 @@ Prerequisites: To create an issue from another issue: 1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). -1. Select **New issue**. +1. Select **New related issue**. 1. Complete the [fields](#fields-in-the-new-issue-form). - The new issue's description is prefilled with `Related to #123`, where `123` is the ID of the - issue of origin. If you keep this mention in the description, the two issues become + The new issue form has a **Relate to issue #123** checkbox, where `123` is the ID of the + issue of origin. If you keep this checkbox checked, the two issues become [linked](related_issues.md). 1. Select **Create issue**. @@ -160,6 +161,9 @@ To regenerate the email address: ### Using a URL with prefilled values +> - Ability to use both `issuable_template` and `issue[description]` in the same URL [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80554) in GitLab 14.9. +> - Ability to specify `add_related_issue` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. + To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external HTML page to create issues with certain fields prefilled. @@ -168,9 +172,10 @@ HTML page to create issues with certain fields prefilled. | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | | Issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| Description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | -| Description | `issue[description]` | Cannot be used at the same time as `issuable_template`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description template | `issuable_template` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | | Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | +| Relate to… | `add_related_issue` | A numeric issue ID. If present, the issue form shows a [**Relate to…** checkbox](#from-another-issue-or-incident) to optionally link the new issue to the specified existing issue. | Adapt these examples to form your new issue URL with prefilled fields. To create an issue in the GitLab project: @@ -264,7 +269,7 @@ When bulk editing issues in a project, you can edit the following attributes: - [Notification](../../profile/notifications.md) subscription - [Iteration](../../group/iterations/index.md) -### Bulk edit issues from a group +### Bulk edit issues from a group **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -573,13 +578,11 @@ To copy the issue's email address: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/3413) in GitLab 13.9. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to -[disable the feature flags](../../../administration/feature_flags.md) named `real_time_issue_sidebar` and `broadcast_issue_updates`. -On GitLab.com, this feature is available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.9. Feature flags `real_time_issue_sidebar` and `broadcast_issue_updates` removed. Assignees in the sidebar are updated in real time. +When you're viewing an issue and somebody changes its assignee, +you can see the change without having to refresh the page. ## Assignee diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index f957d701a3b..279f297d016 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -39,4 +39,4 @@ to assign the issue to.  -To remove an assignee, deselect them from the same dropdown menu. +To remove an assignee, clear them from the same dropdown menu. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index f83ebc5e8a8..b8151ac873a 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -75,4 +75,9 @@ Access our [permissions](../../permissions.md) page for more information. 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). +Issues that block other issues have an icon (**{issue-block}**) next to their title, shown in the +issue lists and [boards](../issue_board.md). +The icon disappears when the blocking issue is closed or their relationship is changed or +[removed](#remove-a-linked-issue). + +If you try to close a blocked issue using the "Close issue" button, a confirmation message appears. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 329f65bfacd..9311ef590df 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -49,7 +49,7 @@ Ties are broken arbitrarily. Only the highest prioritized label is checked, and labels with a lower priority are ignored. For more information, see [issue 14523](https://gitlab.com/gitlab-org/gitlab/-/issues/14523). -To learn more about priority labels, read the [Labels](../labels.md#label-priority) documentation. +To learn how to change label priority, see [Label priority](../labels.md#set-label-priority). ## Sorting by last updated @@ -98,7 +98,9 @@ When you sort by **Priority**, the issue order changes to sort in this order: 1. Issues with a higher priority label. 1. Issues without a prioritized label. -To learn more about priority, read the [Labels](../labels.md#label-priority) documentation. +Ties are broken arbitrarily. + +To learn how to change label priority, see [Label priority](../labels.md#set-label-priority). ## Sorting by title diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 7ccc39eeb8b..18197cd860f 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -6,145 +6,270 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Labels **(FREE)** -As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging +As your count of issues, merge requests, and epics grows in GitLab, it gets more challenging to keep track of those items. Especially as your organization grows from just a few people to -hundreds or thousands. This is where labels come in. They help you organize and tag your work -so you can track and find the work items you're interested in. +hundreds or thousands. With labels, you can organize and tag your work, and track the work items +you're interested in. Labels are a key part of [issue boards](issue_board.md). With labels you can: -- Categorize epics, issues, and merge requests using colors and descriptive titles like +- Categorize [epics](../group/epics/index.md), issues, and merge requests using colors and descriptive titles like `bug`, `feature request`, or `docs`. -- Dynamically filter and manage epics, issues, and merge requests. +- Dynamically filter and manage [epics](../group/epics/index.md), issues, and merge requests. - [Search lists of issues, merge requests, and epics](../search/index.md#search-issues-and-merge-requests), as well as [issue boards](../search/index.md#issue-boards). -## Project labels and group labels +## Types of labels -There are two types of labels in GitLab: +You can use two types of labels in GitLab: - **Project labels** can be assigned to issues and merge requests in that project only. -- **Group labels** can be assigned to issues and merge requests in any project in - the selected group or its subgroups. - - They can also be assigned to epics in the selected group or its subgroups.**(ULTIMATE)** +- **Group labels** can be assigned to issues, merge requests, and [epics](../group/epics/index.md) + in any project in the selected group or its subgroups. ## Assign and unassign labels > Unassigning labels with the **X** button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216881) in GitLab 13.5. -Every issue, merge request, and epic can be assigned any number of labels. The labels are -managed in the right sidebar, where you can assign or unassign labels as needed. +You can assign labels to any issue, merge request, or epic. To assign or unassign a label: -1. In the **Labels** section of the sidebar, click **Edit**. +1. In the **Labels** section of the sidebar, select **Edit**. 1. In the **Assign labels** list, search for labels by typing their names. You can search repeatedly to add more labels. The selected labels are marked with a checkmark. -1. Click the labels you want to assign or unassign. +1. Select the labels you want to assign or unassign. 1. To apply your changes to labels, select **X** next to **Assign labels** or select any area outside the label section. -Alternatively, to unassign a label, click the **X** on the label you want to unassign. +Alternatively, to unassign a label, select the **X** on the label you want to unassign. -You can also assign a label with the `/label` [quick action](quick_actions.md), -remove labels with `/unlabel`, and reassign labels (remove all and assign new ones) with `/relabel`. +You can also assign and unassign labels with [quick actions](quick_actions.md): -## Label management +- Assign labels with `/label`. +- Remove labels with `/unlabel`. +- Remove all labels and assign new ones with `/relabel`. -Users with a [permission level](../permissions.md) of Reporter or higher are able to create -and edit labels. +## View available labels -### Project labels +### View project labels -> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5: the label list in a project also shows all inherited labels. -To view a project's available labels, in the project, go to **Project information > Labels**. -Its list of labels includes both the labels defined at the project level, and -all labels defined by its ancestor groups. For each label, you can see the -project or group path from where it was created. You can filter the list by -entering a search query in the **Filter** field, and then clicking its search -icon (**{search}**). +To view the **project's labels**: -To create a new project label: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. -1. In your project, go to **Project information > Labels**. -1. Select the **New label** button. +Or: + +1. View an issue or merge request. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Manage project labels**. + +The list of labels includes both the labels created in the project and +all labels created in the project's ancestor groups. For each label, you can see the +project or group path where it was created. + +### View group labels + +To view the **group's labels**: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. + +Or: + +1. View an epic. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Manage group labels**. + +The list includes all labels created only in the group. It does not list any labels created in +the group's projects. + +## Create a label + +Prerequisites: + +- You must have at least the Reporter role for the project or group. + +### Create a project label + +To create a project label: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Select **New label**. +1. In the **Title** field, enter a short, descriptive name for the label. You + can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). +1. Optional. In the **Description** field, enter additional + information about how and when to use this label. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color in the **Background color** field. +1. Select **Create label**. + +### Create a project label from an issue or merge request + +You can also create a new project label from an issue or merge request. +Labels you create this way belong to the same project as the issue or merge request. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To do so: + +1. View an issue or merge request. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Create project label**. +1. Fill in the name field. You can't specify a description if creating a label this way. + You can add a description later by [editing the label](#edit-a-label). +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color. +1. Select **Create**. + +### Create a group label + +To create a group label: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. +1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). -1. Optional. In the **Description** field, you can enter additional +1. Optional. In the **Description** field, enter additional information about how and when to use this label. -1. Optional. Select a background color for the label by selecting one of the - available colors, or by entering a hex color value in the **Background color** - field. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color in the **Background color** field. 1. Select **Create label**. -You can also create a new project label from within an issue or merge request. In the -label section of the right sidebar of an issue or a merge request: +### Create a group label from an epic **(PREMIUM)** + +You can also create a new group label from an epic. +Labels you create this way belong to the same group as the epic. + +Prerequisites: + +- You must have at least the Reporter role for the group. -1. Click **Edit**. -1. Click **Create project label**. - - Fill in the name field. Note that you can't specify a description if creating a label - this way. You can add a description later by editing the label (see below). - - Optional. Select a color by clicking on the available colors, or input a hex - color value for a specific color. -1. Click **Create**. +To do so: -To edit a label after you create it, select (**{pencil}**). +1. View an epic. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Create group label**. +1. Fill in the name field. You can't specify a description if creating a label this way. + You can add a description later by [editing the label](#edit-a-label). +1. Optional. Select a color by selecting from the available colors,enter input a hex color value + for a specific color. +1. Select **Create**. -To delete a project label, select (**{ellipsis_v}**) next to the **Subscribe** button -and select **Delete** or select **Delete** when you edit a label. +## Edit a label + +Prerequisites: + +- You must have at least the Reporter role for the project or group. + +### Edit a project label + +To edit a **project** label: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Next to the label you want to edit, select **Edit** (**{pencil}**). + +### Edit a group label + +To edit a **group** label: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. +1. Next to the label you want to edit, select **Edit** (**{pencil}**). + +## Delete a label WARNING: -If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. +If you delete a label, it is permanently deleted. All references to the label are removed from the +system and you cannot undo the deletion. + +Prerequisites: -#### Promote a project label to a group label +- You must have at least the Reporter role for the project. + +### Delete a project label + +To delete a **project** label: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Either: + + - Next to the **Subscribe** button, select (**{ellipsis_v}**). + - Next to the label you want to edit, select **Edit** (**{pencil}**). + +1. Select **Delete**. + +### Delete a group label + +To delete a **group** label: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. +1. Either: + + - Next to the **Subscribe** button, select (**{ellipsis_v}**). + - Next to the label you want to edit, select **Edit** (**{pencil}**). + +1. Select **Delete**. + +## Promote a project label to a group label > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231472) in GitLab 13.6: promoting a project label keeps that label's ID and changes it into a group label. Previously, promoting a project label created a new group label with a new ID and deleted the old label. -If you previously created a project label and now want to make it available for other -projects within the same group, you can promote it to a group label. +You might want to make a project label available for other +projects in the same group. Then, you can promote the label to a group label. If other projects in the same group have a label with the same title, they are all merged with the new group label. If a group label with the same title exists, it is also merged. -All issues, merge requests, issue board lists, issue board filters, and label subscriptions -with the old labels are assigned to the new group label. +WARNING: +Promoting a label is a permanent action and cannot be reversed. -The new group label has the same ID as the previous project label. +Prerequisites: -WARNING: -Promoting a label is a permanent action, and cannot be reversed. +- You must have at least the Reporter role for the project. +- You must have at least the Reporter role for the project's parent group. To promote a project label to a group label: -1. Navigate to **Project information > Labels** in the project. -1. Click on the three dots (**{ellipsis_v}**) next to the **Subscribe** button and +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. -### Group labels +All issues, merge requests, issue board lists, issue board filters, and label subscriptions +with the old labels are assigned to the new group label. + +The new group label has the same ID as the previous project label. -To view the group labels list, navigate to the group and click **Group information > Labels**. -The list includes all labels that are defined at the group level only. It does not -list any labels that are defined in projects. You can filter the list by entering -a search query at the top and clicking search (**{search}**). +## Generate default project labels -To create a **group label**, navigate to **Group information > Labels** in the group and -follow the same process as [creating a project label](#project-labels). +If a project or its parent group has no labels, you can generate a default set of project +labels from the label list page. -#### Create group labels from epics **(ULTIMATE)** +Prerequisites: -You can create group labels from the epic sidebar. The labels you create -belong to the immediate group to which the epic belongs. The process is the same as -creating a [project label from an issue or merge request](#project-labels). +- You must have at least the Reporter role for the project. +- The project must have no labels present. -### Generate default labels +To add the default labels to the project: -If a project or group has no labels, you can generate a default set of project or group -labels from the label list page. The page shows a **Generate a default set of labels** -button if the list is empty. Select the button to add the following default labels -to the project: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Select **Generate a default set of labels**. + +The following labels are created: - `bug` - `confirmed` @@ -157,131 +282,143 @@ to the project: ## Scoped labels **(PREMIUM)** -Scoped labels allow teams to use the label feature to annotate issues, merge requests -and epics with mutually exclusive labels. This can enable more complicated workflows -by preventing certain labels from being used together. - -A label is scoped when it uses a special double-colon (`::`) syntax in the label's -title, for example: +Teams can use scoped labels to annotate issues, merge requests, and epics with mutually exclusive +labels. By preventing certain labels from being used together, you can create more complex workflows.  -An issue, merge request or epic cannot have two scoped labels, of the form `key::value`, -with the same `key`. Adding a new label with the same `key`, but a different `value` -causes the previous `key` label to be replaced with the new label. +A scoped label uses a double-colon (`::`) syntax in its title, for example: `workflow::in-review`. -For example: +An issue, merge request, or epic cannot have two scoped labels, of the form `key::value`, +with the same `key`. If you add a new label with the same `key` but a different `value`, +the previous `key` label is replaced with the new label. -1. An issue is identified as being low priority, and a `priority::low` project - label is added to it. -1. After more review the issue priority is increased, and a `priority::high` label is - added. -1. GitLab automatically removes the `priority::low` label, as an issue should not - have two priority labels at the same time. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Scoped Labels Speed Run](https://www.youtube.com/watch?v=ebyCiKMFODg). ### Filter by scoped labels > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12285) in GitLab 14.4. -To filter issue, merge request, or epic lists for ones with labels that belong to a given scope, enter +To filter issue, merge request, or epic lists by a given scope, enter `<scope>::*` in the searched label name. For example, filtering by the `platform::*` label returns issues that have `platform::iOS`, `platform::Android`, or `platform::Linux` labels. NOTE: -This is not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). +Filtering by scoped labels not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). + +### Scoped labels examples + +**Example 1.** Updating issue priority: + +1. You decide that an issue is of low priority, and assign it the `priority::low` label. +1. After more review, you realize the issue's priority is higher increased, and you assign it the + `priority::high` label. +1. Because an issue shouldn't have two priority labels at the same time, GitLab removes the + `priority::low` label. + +**Example 2.** You want a custom field in issues to track the operating system platform +that your features target, where each issue should only target one platform. + +You create three labels: + +- `platform::iOS` +- `platform::Android` +- `platform::Linux` + +If you assign any of these labels to an issue automatically removes any other existing label that +starts with `platform::`. + +**Example 3.** You can use scoped labels to represent the workflow states of your teams. -### Workflows with scoped labels +Suppose you have the following labels: -Suppose you wanted a custom field in issues to track the operating system platform -that your features target, where each issue should only target one platform. You -would then create three labels `platform::iOS`, `platform::Android`, `platform::Linux`. -Applying any one of these labels on a given issue would automatically remove any other -existing label that starts with `platform::`. +- `workflow::development` +- `workflow::review` +- `workflow::deployed` -The same pattern could be applied to represent the workflow states of your teams. -Suppose you have the labels `workflow::development`, `workflow::review`, and -`workflow::deployed`. If an issue already has the label `workflow::development` -applied, and a developer wanted to advance the issue to `workflow::review`, they -would simply apply that label, and the `workflow::development` label would -automatically be removed. This behavior already exists when you move issues -across label lists in an [issue board](issue_board.md#create-workflows), but -now, team members who may not be working in an issue board directly would still -be able to advance workflow states consistently in issues themselves. +If an issue already has the label `workflow::development` and a developer wants to show that the +issue is now under review, they assign the `workflow::review`, and the `workflow::development` label +is removed. -This functionality is demonstrated in a video regarding -[using scoped labels for custom fields and workflows](https://www.youtube.com/watch?v=4BCBby6du3c). +The same happens when you move issues across label lists in an +[issue board](issue_board.md#create-workflows). With scoped labels, team members not working in an +issue board can also advance workflow states consistently in issues themselves. -### Scoped labels with nested scopes +For a video explanation, see: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=4BCBby6du3c">Use scoped labels for custom fields and custom workflows</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +### Nested scopes You can create a label with a nested scope by using multiple double colons `::` when creating it. In this case, everything before the last `::` is the scope. -For example, `workflow::backend::review` and `workflow::backend::development` are valid -scoped labels, but they **can't** exist on the same issue at the same time, as they -both share the same scope, `workflow::backend`. +For example, if your project has these labels: -Additionally, `workflow::backend::review` and `workflow::frontend::review` are valid -scoped labels, and they **can** exist on the same issue at the same time, as they -both have different scopes, `workflow::frontend` and `workflow::backend`. +- `workflow::backend::review` +- `workflow::backend::development` +- `workflow::frontend::review` -## Subscribing to labels +An issue **can't** have both `workflow::backend::review` and `workflow::backend::development` +labels at the same time, because they both share the same scope: `workflow::backend`. -From the project label list page and the group label list page, you can click **Subscribe** -to the right of any label to enable [notifications](../profile/notifications.md) for that -label. You are notified whenever the label is assigned to an epic, -issue, or merge request. +On the other hand, an issue **can** have both `workflow::backend::review` and `workflow::frontend::review` +labels at the same time, because they both have different scopes: `workflow::frontend` and `workflow::backend`. -If you are subscribing to a group label from within a project, you can select to subscribe -to label notifications for the project only, or the whole group. +## Receive notifications when a label is used - +You can subscribe to a label to [receive notifications](../profile/notifications.md) whenever the +label is assigned to an issue, merge request, or epic. -## Label priority +To subscribe to a label: -Labels can have relative priorities, which are used in the **Label priority** and -**Priority** sort orders of issues and merge request list pages. Prioritization -for both group and project labels happens at the project level, and cannot be done -from the group label list. +1. [View the label list page.](#view-available-labels) +1. To the right of any label, select **Subscribe**. +1. Optional. If you are subscribing to a group label from a project, select either: + - **Subscribe at project level** to be notified about events in this project. + - **Subscribe at group level**: to be notified about events in the whole group. -NOTE: -Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. +## Set label priority -From the project label list page, star a label to indicate that it has a priority. - - +Labels can have relative priorities, which are used when you sort issue and merge request lists +by [label priority](issues/sorting_issue_lists.md#sorting-by-label-priority) and [priority](issues/sorting_issue_lists.md#sorting-by-priority). -Drag starred labels up and down the list to change their priority, where higher in the list -means higher priority. +When prioritizing labels, you must do it from a project. +It's not possible to do it from the group label list. - +NOTE: +Priority sorting is based on the highest priority label only. +[This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. -On the merge request and issue list pages (for both groups and projects) you -can sort by `Label priority` or `Priority`. +Prerequisites: -If you sort by `Label priority`, GitLab uses this sort comparison order: +- You must have at least the Reporter role for the project. -1. Items with a higher priority label. -1. Items without a prioritized label. +To prioritize a label: -Ties are broken arbitrarily. Note that only the highest prioritized label is checked, -and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) -for more information. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Next to a label you want to prioritize, select the star (**{star-o}**). - + -If you sort by `Priority`, GitLab uses this sort comparison order: +This label now appears at the top of the label list, under **Prioritized Labels**. -1. Items with milestones that have due dates, where the soonest assigned [milestone](milestones/index.md) - is listed first. -1. Items with milestones with no due dates. -1. Items with a higher priority label. -1. Items without a prioritized label. +To change the relative priority of these labels, drag them up and down the list. +The labels higher in the list get higher priority. -Ties are broken arbitrarily. + - +To learn what happens when you sort by priority or label priority, see +[Sorting and ordering issue lists](issues/sorting_issue_lists.md). ## Troubleshooting diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8be2ade3f2f..c3d5dca0675 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,16 +10,43 @@ Members are the users and groups who have access to your project. Each member gets a role, which determines what they can do in the project. +Project members can: + +1. Be [direct members](#add-users-to-a-project) of the project. +1. [Inherit membership](#inherited-membership) of the project from the project's group. +1. Be a member of a group that was [shared](share_project_with_groups.md) with the project. +1. Be a member of a group that was [shared with the project's group](../../group/index.md#share-a-group-with-another-group). + +```mermaid +flowchart RL + subgraph Group A + A(Direct member) + B{{Shared member}} + subgraph Project A + H(1. Direct member) + C{{2. Inherited member}} + D{{4. Inherited member}} + E{{3. Shared member}} + end + A-->|Direct membership of Group A\nInherited membership of Project A|C + end + subgraph Group C + G(Direct member) + end + subgraph Group B + F(Direct member) + end + F-->|Group B\nshared with\nGroup A|B + B-->|Inherited membership of Project A|D + G-->|Group C shared with Project A|E +``` + ## 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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Add users to a project so they become members and have permission to perform actions. @@ -52,12 +79,8 @@ using the email address the invitation was sent to. > - [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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. 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: @@ -68,6 +91,7 @@ Each user's access is based on: Prerequisite: - You must have the Maintainer or Owner role. +- Sharing the project with other groups must not be [prevented](../../group/index.md#prevent-a-project-from-being-shared-with-groups). To add groups to a project: @@ -98,11 +122,11 @@ To import users: 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 member** tab, at the bottom of the panel, select **Import**. +1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. -A success message is displayed and the new members are now displayed in the list. +After the success message displays, refresh the page to view the new members. ## Inherited membership @@ -139,7 +163,7 @@ To remove a member from a project: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. -1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Next to the project member you want to remove, select **Remove member**. 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 4e3bae2dc30..02a9b76ce38 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -15,10 +15,14 @@ Groups are used primarily to [create collections of projects](../../group/index. take advantage of the fact that groups define collections of _users_, namely the group members. -## Sharing a project with a group of users +## Share a project with a group of users -NOTE: -In GitLab 13.11, you can [replace this form with a modal window](#share-a-project-modal-window). +> - [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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project @@ -28,9 +32,9 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Project information > Members**. -1. Select the **Invite group** tab. +1. Select **Invite a group**. 1. Add the 'Engineering' group with the maximum access level of your choice. -1. Optional. Select an expiration date. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. After sharing 'Project Acme' with 'Engineering': @@ -45,51 +49,19 @@ You can share a project only with: Administrators can share projects with any group in the system. -### Share a project 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 sharing form with a modal window. -To share a project after enabling this feature: - -1. Go to your project's page. -1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. -1. Select a group, and select a **Max role**. -1. Optional. Select an **Access expiration date**. -1. Select **Invite**. - -### Enable or disable modal window **(FREE SELF)** - -The modal window for sharing a project 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) -``` +## Maximum access level -To disable it: +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. -```ruby -Feature.disable(:invite_members_group_modal) -``` +### Share a project with a subgroup -## Maximum access level +You can't share a project with a group that's an ancestor of a [subgroup](../../group/subgroups/index.md) the project is +in. That means you can only share down the hierarchy. For example, `group/subgroup01/project`: -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. +- Can not be shared with `group`. +- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. -## Sharing public project with private group +## Share public project with private group When sharing a public project with a private group, owners and maintainers of the project see the name of the group in the `members` page. Owners also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index fa447ea35af..01772e59127 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -175,7 +175,7 @@ granting them push access: 1. [Create a new group](../../../group/index.md#create-a-group). 1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. -1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), +1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group-of-users), based on the Reporter role. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1e1c8ccb241..0a7fbc9ee95 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -140,9 +140,7 @@ To learn more, see [Coverage check approval rule](../../../../ci/pipelines/setti > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `group_merge_request_approval_settings_feature_flag`. On GitLab.com, this feature is available. +> - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. You can also enforce merge request approval settings: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 15ba6e9de98..fb41ec3eff6 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -66,11 +66,8 @@ git cherry-pick -m 2 7a39eb0 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11 behind a [feature flag](../../feature_flags.md), disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -You can use the GitLab UI to cherry-pick merge requests into a project, even if the -merge request is from a fork: +You can cherry-pick merge requests from the same project, or forks of the same +project, from the GitLab user interface: 1. In the merge request's secondary menu, click **Commits** to display the commit details page. 1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d735ce0ef91..10fc778d5ae 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -592,17 +592,17 @@ 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" +### Code Quality CI job with Code Climate plugins enabled fails with error -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. +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. +To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.gitlab.-ci.yml` file. For example: diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 0cc18d2117b..b9b65d759dc 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -69,6 +69,7 @@ GitLab creates a squash commit message with this template: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. Commit message templates support these variables: @@ -81,15 +82,20 @@ Commit message templates support these variables: | `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | | `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | -| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge Request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | +| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | | `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | -| `%{approved_by}` | Line-separated list of the merge request approvers. This value is not updated until the first page refresh after an approval. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | +| `%{approved_by}` | Line-separated list of the merge request approvers. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | | `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | +| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| Any line containing only an empty variable is removed. If the line to be removed is both preceded and followed by an empty line, the preceding empty line is also removed. +After you edit a commit message on an open merge request, GitLab will +not automatically update the commit message again. +To restore the commit message to the project template, reload the page. + ## Related topics - [Squash and merge](squash_and_merge.md). diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 0014c1ba994..20e0d3a1f5b 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -31,15 +31,7 @@ To seamlessly navigate among commits in a merge request: > - [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](../../../policy/alpha-beta-support.md#beta-features) -and is [incomplete](https://gitlab.com/groups/gitlab-org/-/epics/1192). - -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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. When reviewing a merge request, it helps to have more context about the changes made. That includes unchanged lines in unchanged files, and previous commits diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 6dbbab316a0..df527ec6ebf 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -18,11 +18,11 @@ The following table shows what attributes will be present in the CSV. | Column | Description | |--------------------|--------------------------------------------------------------| +| Title | Merge request title | +| Description | Merge request description | | MR ID | MR `iid` | | URL | A link to the merge request on GitLab | -| Title | Merge request title | | State | Opened, Closed, Locked, or Merged | -| Description | Merge request description | | Source Branch | Source branch | | Target Branch | Target branch | | Source Project ID | ID of the source project | @@ -39,6 +39,10 @@ The following table shows what attributes will be present in the CSV. | Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | | Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +In GitLab 14.7 and earlier, the first two columns were `MR ID` and `URL`, +which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) +when importing back into GitLab. + ## Limitations - Export merge requests to CSV is not available at the Group's merge request list. diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index cd65fe20e66..dc13b270f17 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -43,7 +43,7 @@ You can also rebase without running a CI/CD pipeline. The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). - + If the target branch is ahead of the source branch and a conflict free rebase is not possible, you need to rebase the diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 8699a42dd5d..fd1751585d5 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -7,7 +7,7 @@ description: "Getting started with merge requests." # Getting started with merge requests **(FREE)** -A merge request (**MR**) is the basis of GitLab as a code +A merge request (**MR**) is the basis of GitLab as a tool for code collaboration and version control. When working in a Git-based platform, you can use branching @@ -161,7 +161,7 @@ enabled by default for all new merge requests, enable it in the [project's settings](../settings/index.md#merge-request-settings). This option is also visible in an existing merge request next to -the merge request button and can be selected or deselected before merging. +the merge request button and can be selected or cleared before merging. It is only visible to users with the Maintainer role in the source project. diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png Binary files differdeleted file mode 100644 index 3c845d277e4..00000000000 --- a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png Binary files differnew file mode 100644 index 00000000000..f4330549a57 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png b/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png Binary files differdeleted file mode 100644 index 7e23b7db309..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index cc4ad186771..7861e1e28fc 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -92,7 +92,7 @@ template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../../ci/runners/build_cloud/linux_build_cloud.md) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/saas/linux_saas_runner.md) likely have insufficient specs to handle most large k6 tests. This template runs the diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md deleted file mode 100644 index 611f37a949b..00000000000 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'conflicts.md' -remove_date: '2022-01-26' ---- - -This document was moved to [another location](conflicts.md). - -<!-- This redirect file can be deleted after <2022-01-26>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index f90296e9626..a1d6959b75e 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -65,7 +65,7 @@ To configure the default squashing behavior for all merge requests in your proje 1. Expand **Merge requests**. 1. In the **Squash commits when merging** section, select your desired behavior: - **Do not allow**: Squashing is never performed, and the option is not displayed. - - **Allow**: Squashing is allowed, but deselected by default. + - **Allow**: Squashing is allowed, but cleared by default. - **Encourage**: Squashing is allowed and selected by default, but can be disabled. - **Require**: Squashing is always performed. While merge requests display the option to squash, users cannot change it. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index bd54eda42f5..d7177208a6e 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -52,7 +52,12 @@ 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. +Uploading a test coverage report does not enable: + +- [Test coverage results in merge requests](../../../ci/pipelines/settings.md#merge-request-test-coverage-results). +- [Code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). + +You must configure these separately. ### Limits diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 165131d50a4..3491346f7d9 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -37,7 +37,7 @@ for the most popular hosting services: - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) - [DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) -- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) +- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/360035516812) - [Gandi](https://docs.gandi.net/en/domain_names/faq/dns_records.html) - [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) - [Hostgator](https://www.hostgator.com/help/article/changing-dns-records) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index ec66dce41f9..4d8919090a2 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -315,7 +315,7 @@ To enable this setting: 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to -`full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). +`full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). <!-- ## Troubleshooting diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 75fc407ce3f..f09aea3b02a 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -79,6 +79,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain-to-pages). 1. Go to step 1. +Another possible cause of this error is the `_redirects` file because the current implementation relies on an HTTP ACME challenge. If you redirect the `.acme-challenge/` endpoint Let's Encrypt cannot validate the domain. Make sure you don't have a wildcard (`*`) redirect either as that too breaks validation. The problem with wildcard redirects is tracked in the [Wildcard redirects break Let's Encrypt integration](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649) issue. + ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 32826346eab..5773dd1f2c0 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -34,7 +34,7 @@ Pages domains are `*.gitlab.io`. | Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| WARNING: -There are some known [limitations](introduction.md#limitations) +There are some known [limitations](introduction.md#subdomains-of-subdomains) regarding namespaces served under the general domain name and HTTPS. Make sure to read that section. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 65e1579001b..e4bc58854ef 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -76,17 +76,21 @@ website.  -## Limitations +## Subdomains of subdomains -When using Pages under the general domain of a GitLab instance (`*.example.io`), -you _cannot_ use HTTPS with sub-subdomains. That means that if your -username or group name contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` does _not_ work. This is a limitation of the -[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). -HTTP pages continue to work provided you don't redirect HTTP to HTTPS. +When using Pages under the top-level domain of a GitLab instance (`*.example.io`), you can't use HTTPS with subdomains +of subdomains. If your namespace or group name contains a dot (for example, `foo.bar`) the domain +`https://foo.bar.example.io` does _not_ work. -GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). -You can only create the highest-level group website. +This limitation is because of the [HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages +work as long as you don't redirect HTTP to HTTPS. + +## GitLab Pages and subgroups + +You must host your GitLab Pages website in a project. This project can belong to a [group](../../group/index.md) or +[subgroup](../../group/subgroups/index.md). For +[group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names), the group must be +at the top level and not a subgroup. ## Specific configuration options for Pages diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 1f60aafe71b..7779f87b459 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -6,4 +6,6 @@ remove_date: '2022-03-14' This file was moved to [another location](custom_domains_ssl_tls_certification/lets_encrypt_integration.md). <!-- This redirect file can be deleted after <2022-03-14>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index beafbc86cb5..cdae1d2f837 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -163,6 +163,12 @@ Splats also match empty strings, so the previous rule redirects ### Rewrite all requests to a root `index.html` +NOTE: +If you are using [GitLab Pages integration with Let’s Encrypt](custom_domains_ssl_tls_certification/lets_encrypt_integration.md), +you must enable it before adding this rule. Otherwise, the redirection breaks the Let's Encrypt +integration. For more details, see +[GitLab Pages issue 649](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649). + Single page applications (SPAs) often perform their own routing using client-side routes. For these applications, it's important that _all_ requests are rewritten to the root `index.html` so that the routing logic can be handled @@ -180,7 +186,7 @@ rule like: Use placeholders in rules to match portions of the requested URL and use these matches when rewriting or redirecting to a new URL. -A placehold is formatted as a `:` character followed by a string of letters +A placeholder is formatted as a `:` character followed by a string of letters (`[a-zA-Z]+`) in both the `from` and `to` paths: ```plaintext diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 8bb18905222..292530e6c9c 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -29,7 +29,7 @@ When a branch is protected, the default behavior enforces these restrictions on ### Set the default branch protection level Administrators can set a default branch protection level in the -[Admin Area](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches). +[Admin Area](../project/repository/branches/default.md#instance-level-default-branch-protection). ## Configure a protected branch @@ -41,7 +41,7 @@ To protect a branch: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. 1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. @@ -58,7 +58,7 @@ To protect multiple branches at the same time: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, type the branch name and a wildcard. +1. From the **Branch** dropdown list, type the branch name and a wildcard. For example: | Wildcard protected branch | Matching branches | @@ -101,7 +101,7 @@ to a protected branch. This is compatible with workflows like the [GitLab workfl 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. 1. From the **Allowed to push** list, select **No one**. 1. Select **Protect**. @@ -112,7 +112,7 @@ You can allow everyone with write access to push to the protected branch. 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** list, select **Developers + Maintainers**. 1. Select **Protect**. @@ -128,27 +128,28 @@ key must have at least read access to the project. Prerequisites: -- The deploy key must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). -- The deploy key must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. +- The deploy key must be enabled for your project. A project deploy key is enabled by default when + it is created. However, a public deploy key must be + [granted](deploy_keys/index.md#grant-project-access-to-a-public-deploy-key) access to the + project. +- The deploy key must have [write access](deploy_keys/index.md#permissions) to your project + repository. To allow a deploy key to push to a protected branch: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** list, select the deploy key. 1. Select **Protect**. -Deploy keys are not available in the **Allowed to merge** dropdown. +Deploy keys are not available in the **Allowed to merge** dropdown list. ## Allow force push on a protected branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to protected branches. @@ -156,7 +157,7 @@ To protect a new branch and enable force push: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. 1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. 1. To reject code pushes that change files listed in the `CODEOWNERS` file, turn on the @@ -169,12 +170,12 @@ To enable force pushes on branches that are already protected: 1. Expand **Protected branches**. 1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. -When enabled, members who are can push to this branch can also force push. +Members who can push to this branch can now also force push. ## Require Code Owner approval on a protected branch **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. -> - [In](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5 and later, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). @@ -182,7 +183,7 @@ To protect a new branch and enable Code Owner's approval: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. 1. Turn on the **Require approval from code owners** toggle. 1. Select **Protect**. @@ -221,7 +222,7 @@ 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. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, type the branch name and select **Delete protected branch**. Protected branches can only be deleted by using GitLab either from the UI or API. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 7d071a45d63..5df34fcdcc4 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -27,18 +27,18 @@ By default: ## Configuring protected tags -To protect a tag, you need to have at least the Maintainer role. +To protect a tag, you must have at least the Maintainer role. 1. Go to the project's **Settings > Repository**. -1. From the **Tag** dropdown menu, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: +1. From the **Tag** dropdown list, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`:  -1. From the **Allowed to create** dropdown, select users with permission to create - matching tags, and click **Protect**: +1. From the **Allowed to create** dropdown list, select users with permission to create + matching tags, and select **Protect**: -  +  1. After done, the protected tag displays in the **Protected tags** list: @@ -61,7 +61,7 @@ Two different wildcards can potentially match the same tag. For example, In that case, if _any_ of these protected tags have a setting like **Allowed to create**, then `production-stable` also inherit this setting. -If you click on a protected tag's name, GitLab displays a list of +If you select a protected tag's name, GitLab displays a list of all matching tags:  diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 8070c37db78..ae42d90af06 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -7,11 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab quick actions **(FREE)** -> - Introduced in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672): +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672) in GitLab 12.1: > once an action is executed, an alert appears when a quick action is successfully applied. -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/16877): you can use +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16877) in GitLab 13.2: you can use > quick actions when updating the description of issues, epics, and merge requests. -> - Introduced in [GitLab 13.8](https://gitlab.com/gitlab-org/gitlab/-/issues/292393): when you enter +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292393) in GitLab 13.8: when you enter > `/` into a description or comment field, all available quick actions are displayed in a scrollable list. > - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. @@ -49,15 +49,15 @@ threads. Some quick actions might not be available to all subscription tiers. | Command | Issue | Merge request | Epic | Action | |:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/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)). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | | `/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. | | `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | | `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | | `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | -| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child 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.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | -| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced in GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/213814)). | +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | | `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | | `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | @@ -68,47 +68,48 @@ threads. Some quick actions might not be available to all subscription tiers. | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. Also, mark both as related. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | | `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | -| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced in GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/213814)). | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | | `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/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. 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)). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/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)). | -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). | +| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | | `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | | `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/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 [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_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](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | | `/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. | -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | | `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/334045). | +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | | `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | | `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | @@ -118,7 +119,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | | `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 8049ee9726d..26b36198bde 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -42,7 +42,7 @@ To view a list of releases: - On the left sidebar, select **Deployments > Releases**, or -- On the project's overview page, if at least one release exists, click the number of releases. +- On the project's overview page, if at least one release exists, select the number of releases.  @@ -52,10 +52,10 @@ To view a list of releases: ### Sort releases -To sort releases by **Released date** or **Created date**, select from the sort order dropdown. To +To sort releases by **Released date** or **Created date**, select from the sort order dropdown list. To switch between ascending or descending order, select **Sort order**. - + ## Create a release @@ -307,9 +307,9 @@ Read more about [Release permissions](#release-permissions). To edit the details of a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). +1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. -1. Click **Save changes**. +1. Select **Save changes**. You can edit the release title, notes, associated milestones, and asset links. To change the release date use the @@ -330,16 +330,16 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). +1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. -1. Click **Save changes**. +1. Select **Save changes**. On the **Deployments > Releases** page, the **Milestone** is listed in the top section, along with statistics about the issues in the milestones.  -Releases are also visible on the **Issues > Milestones** page, and when you click a milestone +Releases are also visible on the **Issues > Milestones** page, and when you select a milestone on this page. Here is an example of milestones with no releases, one release, and two releases, respectively. @@ -360,8 +360,8 @@ You can be notified by email when a new release is created for your project. To subscribe to notifications for releases: 1. On the left sidebar, select **Project information**. -1. Click **Notification setting** (the bell icon). -1. In the list, click **Custom**. +1. Select **Notification setting** (the bell icon). +1. In the list, select **Custom**. 1. Select the **New release** checkbox. 1. Close the dialog box to save. @@ -395,12 +395,12 @@ To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. 1. On the left sidebar, select **Project information**. -1. In the left navigation menu, navigate to **Settings > CI/CD**. +1. In the left navigation menu, go to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. -1. Click **Expand** to see the deploy freeze table. -1. Click **Add deploy freeze** to open the deploy freeze modal. +1. Select **Expand** to see the deploy freeze table. +1. Select **Add deploy freeze** to open the deploy freeze modal. 1. Enter the start time, end time, and time zone of the desired deploy freeze period. -1. Click **Add deploy freeze** in the modal. +1. Select **Add deploy freeze** in the modal. 1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**).  @@ -468,6 +468,28 @@ Each link as an asset has the following attributes: | `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | | `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | +##### Permanent link to latest release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +Latest release page is accessible through a permanent URL. +GitLab will redirect to the latest release page URL when it is visited. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest +``` + +We also support, suffix path carry forward on the redirect to the latest release. +Example if release `v14.8.0-ee` is the latest release and has a readable link `https://host/namespace/project/-/releases/v14.8.0-ee#release` then it can be addressed as `https://host/namespace/project/-/releases/permalink/latest#release`. + +Refer [permanent links to latest release assets](#permanent-links-to-latest-release-assets) section to understand more about the suffix path carry forward usage. + +###### Sorting preferences + +By default, GitLab fetches the release using `released_at` time. The use of the query parameter `?order_by=released_at` is optional, and support for `?order_by=semver` is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). + ##### Permanent links to release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. @@ -475,7 +497,7 @@ Each link as an asset has the following attributes: The assets associated with a release are accessible through a permanent URL. GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue -to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link). +to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link) using the `filepath` API attribute. The format of the URL is: @@ -503,6 +525,36 @@ https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/bin The physical location of the asset can change at any time and the direct link remains unchanged. +##### Permanent links to latest release assets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +The `filepath` from [permanent links to release assets](#permanent-links-to-release-assets) can be used in combination with [permanent link to the latest release](#permanent-link-to-latest-release). It is useful when we want to link a permanant URL to download an asset from the *latest release*. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest/downloads/:filepath +``` + +If you have an asset with [`filepath`](../../../api/releases/links.md#create-a-link) for the `v11.9.0-rc2` latest release in the `gitlab-org` +namespace and `gitlab-runner` project on `gitlab.com`, for example: + +```json +{ + "name": "linux amd64", + "filepath": "/binaries/gitlab-runner-linux-amd64", + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" +} +``` + +This asset has a direct link of: + +```plaintext +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest/downloads/binaries/gitlab-runner-linux-amd64 +``` + ##### Link Types > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. @@ -611,7 +663,7 @@ On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view t  The totals are displayed on [shields](https://shields.io/) and are generated per release by -[a Rake task in the `www-gitlab-com` repo](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). +[a Rake task in the `www-gitlab-com` repository](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). | Item | Formula | | ------ | ------ | @@ -634,7 +686,7 @@ This data is saved in a JSON file and called *release evidence*. The feature includes test artifacts and linked milestones to facilitate internal processes, like external audits. -To access the release evidence, on the Releases page, click the link to the JSON file that's listed +To access the release evidence, on the Releases page, select the link to the JSON file that's listed under the **Evidence collection** heading. You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to @@ -720,7 +772,7 @@ When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifact Although job artifacts normally expire, artifacts included in release evidence do not expire. -To enable job artifact collection you need to specify both: +To enable job artifact collection you must specify both: 1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths) 1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index d706a0e8f8a..f9fd1a48b9a 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -26,7 +26,7 @@ using the GitLab default only if no customizations are set: 1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name. 1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name. 1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name. -1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)** +1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. 1. If no custom default branch name is set at any level, GitLab defaults to: - `main`: Projects created with GitLab 14.0 or later. - `master`: Projects created before GitLab 14.0. @@ -81,13 +81,83 @@ overrides it. Users with at least the Owner role of groups and subgroups can configure the default branch name for a group: 1. Go to the group **Settings > Repository**. -1. Expand **Default initial branch name**. +1. Expand **Default branch**. 1. Change the default initial branch to a custom name of your choice. 1. Select **Save changes**. Projects created in this group after you change the setting use the custom branch name, unless a subgroup configuration overrides it. +## Protect initial default branches **(FREE SELF)** + +GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md) +to apply to every repository's [default branch](#default-branch) +at the [instance level](#instance-level-default-branch-protection) and +[group level](#group-level-default-branch-protection) with one of the following options: + +- **Not protected** - Both developers and maintainers can push new commits + and force push. +- **Protected against pushes** - Developers cannot push new commits, but are + allowed to accept merge requests to the branch. Maintainers can push to the branch. +- **Partially protected** - Both developers and maintainers can push new commits, + but cannot force push. +- **Fully protected** - Developers cannot push new commits, but maintainers can. + No one can force push. + +### Instance-level default branch protection **(FREE SELF)** + +This setting applies only to each repository's default branch. To protect other branches, +you must either: + +- Configure [branch protection in the repository](../../../project/protected_branches.md). +- Configure [branch protection for groups](../../../group/index.md#change-the-default-branch-protection-of-a-group). + +Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual +groups and subgroups can override this instance-wide setting for their projects. + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Default branch**. +1. Select [**Initial default branch protection**](#protect-initial-default-branches). +1. To allow group owners to override the instance's default branch protection, select + [**Allow owners to manage default branch protection per group**](#prevent-overrides-of-default-branch-protection). +1. Select **Save changes**. + +#### Prevent overrides of default branch protection **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0. + +Instance-level protections for default branches +can be overridden on a per-group basis by the group's owner. In +[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +disable this privilege for group owners, enforcing the instance-level protection rule: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. +1. Expand the **Default branch** section. +1. Clear the **Allow owners to manage default branch protection per group** checkbox. +1. Select **Save changes**. + +NOTE: +GitLab administrators can still update the default branch protection of a group. + +### Group-level default branch protection **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. +> - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. + +Instance-level protections for [default branch](#default-branch) +can be overridden on a per-group basis by the group's owner. In +[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +[enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) +which locks this setting for group owners. + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Default branch**. +1. Select [**Initial default branch protection**](#protect-initial-default-branches). +1. Select **Save changes**. + ## Update the default branch name in your repository WARNING: diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index b085372c8f2..ddeef65a6b5 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -18,36 +18,24 @@ submit them through a merge request to the repository you don't have access to. ## Creating a fork -To fork an existing project in GitLab: - -1. On the project's home page, in the top right, click **{fork}** **Fork**. - -  - -1. Select the project to fork to: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) a new form in GitLab 13.11 [with a flag](../../../user/feature_flags.md) named `fork_project_form`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77181) in GitLab 14.8. Feature flag `fork_project_form` removed. - - Recommended method. Below **Select a namespace to fork the project**, identify - the project you want to fork to, and click **Select**. Only namespaces where you have - at least the Developer role for are shown. - -  - - - Experimental method. If your GitLab administrator has - 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 where you have at least the Developer role for are shown. - - NOTE: - The project path must be unique in the namespace. +To fork an existing project in GitLab: -GitLab creates your fork, and redirects you to the project page for your new fork. -The permissions you have in the namespace are your permissions in the fork. +1. On the project's home page, in the top right, select **{fork}** **Fork**: +  +1. Optional. Edit the **Project name**. +1. For **Project URL**, select the [namespace](../../group/index.md#namespaces) + your fork should belong to. +1. Add a **Project slug**. This value becomes part of the URL to your fork. + It must be unique in the namespace. +1. Optional. Add a **Project description**. +1. Select the **Visibility level** for your fork. For more information about + visibility levels, read [Project and group visibility](../../../public_access/public_access.md). +1. Select **Fork project**. -WARNING: -When a public project with the repository feature set to **Members Only** -is forked, the repository is public in the fork. The owner -of the fork must manually change the visibility. Issue -[#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662) exists for this issue. +GitLab creates your fork, and redirects you to the new fork's page. ## Repository mirroring @@ -59,7 +47,7 @@ Without mirroring, to work locally you must use `git pull` to update your local with the upstream project, then push the changes back to your fork to update it. WARNING: -With mirroring, before approving a merge request, you are asked to sync. Because of this, automating it is recommended. +With mirroring, before approving a merge request, you are asked to sync. We recommend you automate it. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -75,30 +63,9 @@ When creating a merge request, if the forked project's visibility is more restri  Then you can add labels, a milestone, and assign the merge request to someone who can review -your changes. Then click **Submit merge request** to conclude the process. When successfully merged, your +your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#removing-a-fork-relationship). - -## Create a fork with 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. - -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: - - - -To use it, follow the instructions at [Creating a fork](#creating-a-fork) and provide: - -- The project name. -- The project URL. -- The project slug. -- Optional. The project description. -- The visibility level for your fork. diff --git a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png b/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png Binary files differdeleted file mode 100644 index 6e2ff33eebb..00000000000 --- a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png +++ /dev/null diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index f5cea8a8075..00998c9a227 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -6,129 +6,96 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Signing commits with GPG **(FREE)** -You can use a GPG key to sign Git commits made in a GitLab repository. Signed -commits are labeled **Verified** if the identity of the committer can be -verified. To verify the identity of a committer, GitLab requires their public -GPG key. +You can sign the commits you make in a GitLab repository with a +GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic +signature to your commit, you provide extra assurance that a commit +originated from you, rather than an impersonator. If GitLab can verify a commit +author's identity with a public GPG key, the commit is marked **Verified** in the +GitLab UI. You can then configure [push rules](../push_rules.md#enabling-push-rules) +for your project to reject individual commits not signed with GPG, or reject all +commits from unverified users. NOTE: -The term GPG is used for all OpenPGP/PGP/GPG related material and +GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and implementations. -To view a user's public GPG key, you can: - -- Go to `https://gitlab.example.com/<username>.gpg`. -- Select **View public GPG keys** (**{key}**) in the top right of the user's profile. - -GPG verified tags are not supported yet. - -See the [further reading](#further-reading) section for more details on GPG. - -## How GitLab handles GPG - -GitLab uses its own keyring to verify the GPG signature. It does not access any -public key server. - -For a commit to be verified by GitLab: +For GitLab to consider a commit verified: - The committer must have a GPG public/private key pair. -- The committer's public key must have been uploaded to their GitLab - account. -- One of the emails in the GPG key must match a **verified** email address - used by the committer in GitLab. This address will be part of the public key. - If you want to keep this address private, use the automatically generated +- The committer's public key must be uploaded to their GitLab account. +- One of the email addresses in the GPG public key must match a **verified** email address + used by the committer in GitLab. To keep this address private, use the automatically generated [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) GitLab provides in your profile. - The committer's email address must match the verified email address from the GPG key. -## Generating a GPG key - -If you don't already have a GPG key, the following steps can help you get -started: - -1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. - If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in - the following commands. -1. Generate the private/public key pair with the command appropriate for your version - of `gpg`. This command spawns a series of questions: - - ```shell - # Use this command for the default version of gpg, including - # Gpg4win on Windows, and most macOS versions: - gpg --gen-key +GitLab uses its own keyring to verify the GPG signature. It does not access any +public key server. - # Use this command for versions of GPG later than 2.1.17: - gpg --full-gen-key - ``` +GPG verified tags are not supported. -1. The first question is which algorithm can be used. Select the kind you want - or press <kbd>Enter</kbd> to choose the default (RSA and RSA): +For more details about GPG, refer to the [related topics list](#related-topics). - ```plaintext - Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - Your selection? 1 - ``` +## View a user's public GPG key -1. The next question is key length. We recommend you choose `4096`: +To view a user's public GPG key, you can either: - ```plaintext - RSA keys may be between 1024 and 4096 bits long. - What keysize do you want? (2048) 4096 - Requested keysize is 4096 bits - ``` +- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, + if the user has configured one, or a blank page for users without a configured GPG key. +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right + of the user's profile, select **View public GPG keys** (**{key}**). -1. Specify the validity period of your key. This is something - subjective, and you can use the default value, which is to never expire: +## Configure commit signing - ```plaintext - Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years - Key is valid for? (0) 0 - Key does not expire at all - ``` +To sign commits, you must configure both your local machine and your GitLab account: -1. Confirm that the answers you gave were correct by typing `y`: +1. [Create a GPG key](#create-a-gpg-key). +1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). +1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). +1. [Sign your Git commits](#sign-your-git-commits). - ```plaintext - Is this correct? (y/N) y - ``` +### Create a GPG key -1. Enter your real name, the email address to be associated with this key - (should match a verified email address you use in GitLab) and an optional - comment (press <kbd>Enter</kbd> to skip): +If you don't already have a GPG key, create one: - ```plaintext - GnuPG needs to construct a user ID to identify your key. +1. [Install GPG](https://www.gnupg.org/download/) for your operating system. + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in + the commands on this page. +1. To generate your key pair, run the command appropriate for your version of `gpg`: - Real name: Mr. Robot - Email address: <your_email> - Comment: - You selected this USER-ID: - "Mr. Robot <your_email>" + ```shell + # Use this command for the default version of GPG, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key - Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + # Use this command for versions of GPG later than 2.1.17: + gpg --full-gen-key ``` -1. Pick a strong password when asked and type it twice to confirm. -1. Use the following command to list the private GPG key you just created: +1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select + the default option, `RSA and RSA`. +1. Select the key length, in bits. GitLab recommends 4096-bit keys. +1. Specify the validity period of your key. This value is subjective, and the + default value is no expiration. +1. To confirm your answers, enter `y`. +1. Enter your name. +1. Enter your email address. It must match a + [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) + in your GitLab account. +1. Optional. Enter a comment to display in parentheses after your name. +1. GPG displays the information you've entered so far. Edit the information or press + <kbd>O</kbd> (for `Okay`) to continue. +1. Enter a strong password, then enter it again to confirm it. +1. To list your private GPG key, run this command, replacing + `<EMAIL>` with the email address you used when you generated the key: ```shell - gpg --list-secret-keys --keyid-format LONG <your_email> + gpg --list-secret-keys --keyid-format LONG <EMAIL> ``` - Replace `<your_email>` with the email address you entered above. - -1. Copy the GPG key ID that starts with `sec`. In the following example, that's - `30F2B65B9246B6CA`: +1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after + the `/` character. In this example, the key ID is `30F2B65B9246B6CA`: ```plaintext sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] @@ -137,49 +104,46 @@ started: ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` -1. Export the public key of that ID (replace your key ID from the previous step): +1. To show the associated public key, run this command, replacing `<ID>` with the + GPG key ID from the previous step: ```shell - gpg --armor --export 30F2B65B9246B6CA + gpg --armor --export <ID> ``` -1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account) +1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and + `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step. -## Adding a GPG key to your account +### Add a GPG key to your account -NOTE: -After you add a key, you cannot edit it, only remove it. In case the paste -didn't work, you have to remove the offending key and re-add it. - -You can add a GPG key in your user settings: +To add a GPG key to your user settings: +1. Sign in to GitLab. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. -1. Paste your _public_ key in the **Key** text box. - -  - -1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding - email address, and creation date. +1. On the left sidebar, select **GPG Keys** (**{key}**). +1. In **Key**, paste your _public_ key. +1. To add the key to your account, select **Add key**. GitLab shows the key's + fingerprint, email address, and creation date:  -## Associating your GPG key with Git +After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. -After you have [created your GPG key](#generating-a-gpg-key) and [added it to -your account](#adding-a-gpg-key-to-your-account), it's time to tell Git which -key to use. +### Associate your GPG key with Git -1. Use the following command to list the private GPG key you just created: +After you [create your GPG key](#create-a-gpg-key) and +[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git +to use this key: + +1. Run this command to list the private GPG key you just created, + replacing `<EMAIL>` with the email address for your key: ```shell - gpg --list-secret-keys --keyid-format LONG <your_email> + gpg --list-secret-keys --keyid-format LONG <EMAIL> ``` - Replace `<your_email>` with the email address you entered above. - -1. Copy the GPG key ID that starts with `sec`. In the following example, that's +1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is `30F2B65B9246B6CA`: ```plaintext @@ -189,114 +153,103 @@ key to use. ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` -1. Tell Git to use that key to sign the commits: +1. Run this command to configure Git to sign your commits with your key, + replacing `<KEY ID>` with your GPG key ID: ```shell - git config --global user.signingkey 30F2B65B9246B6CA + git config --global user.signingkey <KEY ID> ``` - Replace `30F2B65B9246B6CA` with your GPG key ID. - -1. Optional. If Git is using `gpg` and you get errors like `secret key not available` - or `gpg: signing failed: secret key not available`, run the following command to - change to `gpg2`: +1. Optional. If Git uses `gpg` and you get errors like `secret key not available` + or `gpg: signing failed: secret key not available`, run this command to + use `gpg2` instead: ```shell git config --global gpg.program gpg2 ``` -## Signing commits +### Sign your Git commits -After you have [created your GPG key](#generating-a-gpg-key) and [added it to -your account](#adding-a-gpg-key-to-your-account), you can start signing your -commits: +After you [add your public key to your account](#add-a-gpg-key-to-your-account), +you can sign individual commits manually, or configure Git to default to signed commits: -1. Commit like you used to, the only difference is the addition of the `-S` flag: +- Sign individual Git commits manually: + 1. Add `-S` flag to any commit you want to sign: - ```shell - git commit -S -m "My commit msg" - ``` + ```shell + git commit -S -m "My commit message" + ``` -1. Enter the passphrase of your GPG key when asked. -1. Push to GitLab and check that your commits [are verified](#verifying-commits). + 1. Enter the passphrase of your GPG key when asked. + 1. Push to GitLab and check that your commits [are verified](#verify-commits). +- Sign all Git commits by default by running this command: -If you don't want to type the `-S` flag every time you commit, you can tell Git -to sign your commits automatically: + ```shell + git config --global commit.gpgsign true + ``` -```shell -git config --global commit.gpgsign true -``` +## Verify commits -## Verifying commits +You can review commits for a merge request, or for an entire project: -1. Within a project or [merge request](../../merge_requests/index.md), navigate to - the **Commits** tab. Signed commits show a badge containing either - **Verified** or **Unverified**, depending on the verification status of the GPG - signature. +1. To review commits for a project: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Repository > Commits**. +1. To review commits for a merge request: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. Select **Commits**. +1. Identify the commit you want to review. Signed commits show either a **Verified** + or **Unverified** badge, depending on the verification status of the GPG + signature. Unsigned commits do not display a badge:  -1. By clicking on the GPG badge, details of the signature are displayed. +1. To display the signature details for a commit, select the GPG badge:  -  +  -## Revoking a GPG key +## Revoke a GPG key -Revoking a key **unverifies** already signed commits. Commits that were -verified by using this key changes to an unverified state. Future commits -stay unverified after you revoke this key. This action should be used -in case your key has been compromised. +If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. To revoke a GPG key: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. -## Removing a GPG key +## Remove a GPG key + +When you remove a GPG key from your GitLab account: -Removing a key **does not unverify** already signed commits. Commits that were -verified by using this key stay verified. Only unpushed commits stay -unverified after you remove this key. To unverify already signed commits, you need -to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. +- Previous commits signed with this key remain verified. +- Future commits (including any commits created but not yet pushed) that attempt + to use this key are unverified. To remove a GPG key from your account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. -1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. - -## 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.md). - -## GPG signing API - -Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit). - -## Further reading - -For more details about GPG, see: - -- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) -- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) -- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) -- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) -- [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) - -<!-- ## 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. --> +1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. + +If you must unverify both future and past commits, +[revoke the associated GPG key](#revoke-a-gpg-key) instead. + +## Related topics + +- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) +- [Commits API](../../../../api/commits.md) +- GPG resources: + - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) + - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) + - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) + - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + - [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) diff --git a/doc/user/project/repository/img/fork_form_v13_10.png b/doc/user/project/repository/img/fork_form_v13_10.png Binary files differdeleted file mode 100644 index 00c2f89a844..00000000000 --- a/doc/user/project/repository/img/fork_form_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png Binary files differdeleted file mode 100644 index 74f65cb663d..00000000000 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 5646f478d9f..cd0c6679d8d 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,11 +25,8 @@ GitLab. ## Cleaner diffs -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. 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 `jupyter_clean_diffs`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. When commits include changes to Jupyter Notebook files, GitLab: diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index cddbc6fd891..c9fa30e39a8 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -96,9 +96,7 @@ Prerequisite: 1. Select **Update now** (**{retry}**):  -## Mirror only protected branches **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. +## Mirror only protected branches You can choose to mirror only the [protected branches](../../protected_branches.md) in the mirroring project, diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 221616bd41c..ebc4430ac53 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -76,7 +76,7 @@ through the [remote mirrors API](../../../../api/remote_mirrors.md). To configure a mirror from GitLab to GitHub: -1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) +1. Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `public_repo` selected. 1. Enter a **Git repository URL** with this format: `https://<your_access_token>@github.com/<github_group>/<github_project>.git`. 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 37b16d90d93..83fafd409e8 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 @@ -13,8 +13,6 @@ Git repositories become larger over time. When large files are added to a Git re - They take up a large amount of storage space on the server. - Git repository storage limits [can be reached](#storage-limits). -Such problems can be detected with [git-sizer](https://github.com/github/git-sizer#getting-started). - Rewriting a repository can remove unwanted history to make the repository smaller. We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/README.md)** over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and @@ -40,7 +38,8 @@ These refs are not automatically downloaded and hidden refs are not advertised, To purge files from a GitLab repository: -1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) +1. Install either [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) or + [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. 1. Generate a fresh [export from the @@ -63,31 +62,43 @@ To purge files from a GitLab repository: git clone --bare --mirror /path/to/project.bundle ``` -1. Navigate to the `project.git` directory: +1. Go to the `project.git` directory: ```shell cd project.git ``` -1. Using `git filter-repo`, purge any files from the history of your repository. Because we are +1. Using either `git filter-repo` or `git-sizer`, analyze your repository + and review the results to determine which items you want to purge: + + ```shell + # Using git filter-repo + git filter-repo --analyze + head .git/filter-repo/analysis/*-{all,deleted}-sizes.txt + + # Using git-sizer + git-sizer + ``` + +1. Proceed to purging any files from the history of your repository. Because we are trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. NOTE: - `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from + `git filter-repo` creates a new `commit-map` file every run, and overwrites the `commit-map` from the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. - To purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: + To purge specific files, the `--path` and `--invert-paths` options can be combined: ```shell - git filter-repo --strip-blobs-bigger-than 10M + git filter-repo --path path/to/file.ext --invert-paths ``` - To purge specific large files by path, the `--path` and `--invert-paths` options can be combined. + To generally purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: ```shell - git filter-repo --path path/to/big/file.m4v --invert-paths + git filter-repo --strip-blobs-bigger-than 10M ``` See the @@ -148,7 +159,7 @@ operations before continuing. To clean up a repository: 1. Go to the project for the repository. -1. Navigate to **Settings > Repository**. +1. Go to **Settings > Repository**. 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. @@ -158,7 +169,7 @@ To clean up a repository: split -l 3000 filter-repo/commit-map filter-repo/commit-map- ``` -1. Click **Start cleanup**. +1. Select **Start cleanup**. This: @@ -229,7 +240,7 @@ Until `git gc` runs on the GitLab side, the "removed" commits and blobs still ex must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. -In order to lift these restrictions, the administrator of the self-managed GitLab instance must +To lift these restrictions, the Administrator of the self-managed GitLab instance must increase the limit on the particular project that exceeded it. Therefore, it's always better to proactively stay underneath the limit. If you hit the limit, and can't have it temporarily increased, your only option is to: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 27ef14d31c5..c9cddad1a91 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -20,15 +20,15 @@ The main difference is the way GitLab determines whether or not the developer's (A trust store is a repository of trusted security certificates.) Combined with any required intermediate certificates in the signature, the developer's certificate can be chained back to a trusted root certificate. -- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account) +- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#add-a-gpg-key-to-your-account) to their account. GitLab uses its own certificate store and therefore defines the -[trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/). +[trust chain](https://www.ssl.com/faqs/what-is-a-certificate-authority/). For a commit or tag to be *verified* by GitLab: - The signing certificate email must match a verified email address in GitLab. -- The GitLab instance must be able to establish a full [trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/) +- The GitLab instance must be able to establish a full trust chain from the certificate in the signature to a trusted certificate in the GitLab certificate store. This chain may include intermediate certificates supplied in the signature. You may need to add certificates, such as Certificate Authority root certificates, diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index d549a22910a..6abe9c08d28 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: In 14.4, Requirements was moved under **Issues**. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -> - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in GitLab 12.10. +> - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in GitLab 13.5. > - [Moved under Issues](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70748) in 14.4 With requirements, you can set criteria to check your products against. They can be based on users, @@ -64,7 +64,7 @@ next to the requirement title. ## Edit a requirement -> The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in GitLab 13.5. You can edit a requirement from the requirements list page. @@ -108,7 +108,7 @@ As soon as a requirement is reopened, it no longer appears in the **Archived** t ## Search for a requirement -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in GitLab 13.1. > - Searching by status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224614) in GitLab 13.10. You can search for a requirement from the requirements list page based on the following criteria: @@ -131,8 +131,8 @@ You can also sort the requirements list by: ## Allow requirements to be satisfied from a CI job -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in GitLab 13.2. GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 1e5b818c99d..90732ba4fe2 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -41,7 +41,7 @@ Here's how Service Desk works for you: 1. You provide a project-specific email address to your paying customers, who can email you directly from the application. 1. Each email they send creates an issue in the appropriate project. -1. Your team members navigate to the Service Desk issue tracker, where they can see new support +1. Your team members go to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues. 1. Your team communicates back and forth with the customer to understand the request. 1. Your team starts working on implementing code to solve your customer's problem. @@ -93,8 +93,8 @@ displayed in the information note. ### Using customized email templates -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab Premium 12.7. -> - Moved to GitLab Free in 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab 12.7. +> - Moved from GitLab Premium to GitLab Free in 13.2. An email is sent to the author when: @@ -153,7 +153,7 @@ To use a custom description template with Service Desk: 1. On the top bar, select **Menu > Projects** and find your project. 1. [Create a description template](description_templates.md#create-an-issue-template). 1. On the left sidebar, select **Settings > General > Service Desk**. -1. From the dropdown **Template to append to all Service Desk issues**, search or select your template. +1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. ### Using a custom email display name @@ -171,7 +171,7 @@ To edit the custom email display name: ### Using a custom email address **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. It is possible to customize the email address used by Service Desk. To do this, you must configure @@ -190,13 +190,13 @@ you can customize the mailbox used by Service Desk. This allows you to have a separate email address for Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. -The `address` must include the `+%{key}` placeholder within the 'user' -portion of the address, before the `@`. This is used to identify the project +The `address` must include the `+%{key}` placeholder in the 'user' +portion of the address, before the `@`. The placeholder is used to identify the project where the issue should be created. NOTE: When configuring a custom mailbox, the `service_desk_email` and `incoming_email` -configurations must always use separate mailboxes. This is important, because +configurations must always use separate mailboxes. It's important, because emails picked from `service_desk_email` mailbox are processed by a different worker and it would not recognize `incoming_email` emails. @@ -241,7 +241,7 @@ The configuration options are the same as for configuring ##### Microsoft Graph -> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). @@ -267,7 +267,7 @@ The Microsoft Graph API is not yet supported in source installations. See [this #### Configuring a custom email address suffix -You can set a custom suffix in your project's Service Desk settings once you have configured a [custom mailbox](#configuring-a-custom-mailbox). +You can set a custom suffix in your project's Service Desk settings after you have configured a [custom mailbox](#configuring-a-custom-mailbox). It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). When configured, the custom suffix creates a new Service Desk email address, consisting of the @@ -281,7 +281,7 @@ For example, suppose the `mygroup/myproject` project Service Desk settings has t The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. The [incoming email](../../administration/incoming_email.md) address still works. -If you don't configure the custom suffix, the default project identification will be used for identifying the project. You can see that email address in the project settings. +If you don't configure the custom suffix, the default project identification is used for identifying the project. You can see that email address in the project settings. ## Using Service Desk @@ -292,6 +292,7 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo > Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. > In earlier versions, the Service Desk email address had to be in the "To" field. + To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and receive an email back confirming receipt: @@ -327,7 +328,28 @@ You can read and write comments as you normally do in GitLab: Note that: - The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, are shown in emails. +- The path to the project, including its group or namespace, is shown in emails. + +#### Issues created on someone's behalf + +To allow third party applications and ticketing systems to interface with Service Desk, +when the email contains the `Reply-To` email header, this email address is used as the address of the +issue author. + +Because the `Reply-To` header can be set to arbitrary values, do not blindly trust that an issue +created on behalf of `someone@example.com` was indeed created by the real owner of such email address. + +For example, an email with headers `To: support@example.com` and `Reply-To:someone@example.com` +creates an issue with the following note: + +> Created (…) by `support@example.com` (reply to: `someone@example.com`) (…) + +#### Privacy considerations + +Service Desk issues are confidential, but the project owner can +[make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). +When a Service Desk issue becomes public, the issue creator's email address is disclosed +to everyone who can view the project. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 8cee567ae93..ae3decb8079 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -229,7 +229,7 @@ and the exports between them are compatible. ## Related topics - [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) - [Group import/export](../../group/settings/import_export.md) - [Group import/export API](../../../api/group_import_export.md) @@ -305,6 +305,9 @@ reduce the repository size for another import attempt: #### Workaround option 2 +NOTE: +This workaround requires access to the rails console, which isn't available to end-users on GitLab.com. + Rather than attempting to push all changes at once, this workaround: - Separates the project import from the Git Repository import @@ -351,32 +354,32 @@ Rather than attempting to push all changes at once, this workaround: git push -u origin ${COMMIT_SHA}:refs/heads/main done git push -u origin main - git push -u origin -—all - git push -u origin -—tags + git push -u origin --all + git push -u origin --tags ``` ### Manually execute export steps Exports sometimes fail without giving enough information to troubleshoot. In these cases, it can be -helpful to [execute the export process manually within rails](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/uncategorized/project-export.md#export-a-project-via-rails-console). +helpful to [open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +and loop through [all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/b67a5b5a12498d57cd877023b7385f7251e57de8/app/services/projects/import_export/export_service.rb#L65). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. ```shell +# User needs to have permission to export u = User.find_by_username('someuser') p = Project.find_by_full_path('some/project') e = Projects::ImportExport::ExportService.new(p,u) e.send(:version_saver).send(:save) -e.send(:avatar_saver).send(:save) -e.send(:project_tree_saver).send(:save) -e.send(:uploads_saver).send(:save) -e.send(:wiki_repo_saver).send(:save) -e.send(:lfs_saver).send(:save) -e.send(:snippets_repo_saver).send(:save) -e.send(:design_repo_saver).send(:save) +e.send(:repo_saver).send(:save) +## continue using `e.send(:exporter_name).send(:save)` going through the list of exporters +# The following line should show you the export_path similar to /var/opt/gitlab/gitlab-rails/shared/tmp/gitlab_exports/@hashed/49/94/4994.... s = Gitlab::ImportExport::Saver.new(exportable: p, shared:p.import_export_shared) + +# To try and upload use: s.send(:compress_and_save) s.send(:save_upload) ``` diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 12d75551aac..342b8d80bcf 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -541,7 +541,7 @@ Configure [alert integrations](../../../operations/incident_management/integrati #### Alert integration -Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. +Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. #### PagerDuty integration @@ -555,11 +555,11 @@ Automatically [create](../../../operations/incident_management/incidents.md#crea Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). -### Jaeger tracing **(ULTIMATE)** +### Jaeger tracing Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../../../operations/tracing.md). -### Status Page +### Status Page **(ULTIMATE)** [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index aa30c576c7c..a78226ac2f8 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -24,6 +24,8 @@ Project access tokens are similar to [group access tokens](../../group/settings/ and [personal access tokens](../../profile/personal_access_tokens.md), except they are associated with a project rather than a group or user. +In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) as personal access tokens if the limit is set. + You can use project access tokens: - On GitLab SaaS if you have the Premium license tier or higher. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). @@ -43,7 +45,8 @@ 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. 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. Optional. Enter an expiry date for the token. The token expires on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. + 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). 1. Select **Create project access token**. diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 072f5bf1927..7c74a625b92 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -18,18 +18,13 @@ 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). +[removal](https://gitlab.com/groups/gitlab-org/-/epics/7351) in GitLab 14.10. +Users should instead use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md). [Removal instructions](#remove-the-static-site-editor) for existing projects are included on this page. Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or Git commands. A contributor to your project can quickly edit a Markdown page -and submit the changes for review. - -## Use cases - -The Static Site Editor allows collaborators to submit changes to static site -files seamlessly. For example: +and submit the changes for review. For example: - Non-technical collaborators can edit a page directly from the browser. They don't need to know Git and the details of your project to contribute. @@ -37,6 +32,43 @@ files seamlessly. For example: - Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. +## Remove the Static Site Editor + +The Static Site Editor itself isn't part of your project. To remove the Static Site Editor +from an existing project, remove links that point back to the editor: + +1. Remove any links that use `edit_page_url` in your project. If you used the + **Middleman - Static Site Editor** project template, the only instance of this + helper is located in `/source/layouts/layout.erb`. Remove this line entirely: + + ```ruby + <%= link_to('Edit this page', edit_page_url(data.config.repository, current_page.file_descriptor.relative_path), id: 'edit-page-link') %> + ``` + +1. In `/data/config.yml`, delete the `repository` key / value pair: + + ```yaml + repository: https://gitlab.com/<username>/<myproject> + ``` + + - If `repository` is the only value stored in `/data/config.yml`, you can delete the entire file. +1. In `/helpers/custom_helpers.rb`, delete `edit_page_url()` and `endcode_path()`: + + ```ruby + def edit_page_url(base_url, relative_path) + "#{base_url}/-/sse/#{encode_path(relative_path)}/" + end + + def encode_path(relative_path) + ERB::Util.url_encode("master/source/#{relative_path}") + end + ``` + + - If `edit_page_url()` and `encode_path()` are the only helpers, you may delete + `/helpers/custom_helpers.rb` entirely. +1. Clean up any extraneous configuration files. +1. Commit and push your changes. + ## Requirements - In order use the Static Site Editor feature, your project needs to be diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 4565b5f1c91..ff8a076465d 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -17,16 +17,16 @@ You can also open the Web IDE when viewing a file, from the repository file list and from merge requests: - *When viewing a file, or the repository file list* - - 1. In the upper right corner of the page, select **Edit in Web IDE** if it is visible. - 1. If **Edit in Web IDE** is not visible: + 1. In the upper right corner of the page, select **Open in Web IDE** if it is visible. + 1. If **Open in Web IDE** is not visible: 1. Select the **(angle-down)** next to **Edit** or **Gitpod**, depending on your configuration. - 1. Select **Edit in Web IDE** from the list to display it as the editing option. - 1. Select **Edit in Web IDE** to open the editor. + 1. Select **Open in Web IDE** from the list to display it as the editing option. + 1. Select **Open in Web IDE** to open the editor. - *When viewing a merge request* - 1. Go to your merge request, and select the **Overview** tab. 1. Scroll to the widgets section, after the merge request description. - 1. Select **Edit in Web IDE** if it is visible. - 1. If **Edit in Web IDE** is not visible: + 1. Select **Open in Web IDE** if it is visible. + 1. If **Open in Web IDE** is not visible: 1. Select the **(angle-down)** next to **Open in Gitpod**. 1. Select **Open in Web IDE** from the list to display it as the editing option. 1. Select **Open in Web IDE** to open the editor. @@ -145,7 +145,7 @@ Each schema entry supports two properties: ## Configure the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in GitLab Free 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in GitLab 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -164,8 +164,8 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes -> - Starting with [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files are automatically staged. -> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All of your current changes must be committed or discarded. +> - [Starting](https://gitlab.com/gitlab-org/gitlab/-/issues/33441) with GitLab 12.7, files are automatically staged. +> - In GitLab 12.9, support for staging files was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/196609) to prevent loss of unstaged data. All of your current changes must be committed or discarded. After making your changes, select **Commit** on the bottom-left to review the list of changed files. @@ -215,13 +215,13 @@ different branch. ## Markdown editing -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in GitLab Free 13.1. -> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in GitLab Free 14.3. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in GitLab 13.1. +> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in GitLab 14.3. To edit Markdown files in the Web IDE: 1. Go to your repository, and navigate to the Markdown page you want to edit. -1. Select **Edit in Web IDE**, and GitLab loads the page in a tab in the editor. +1. Select **Open in Web IDE**, and GitLab loads the page in a tab in the editor. 1. Make your changes to the file. GitLab supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). 1. When your changes are complete, select **Commit** in the left sidebar. 1. Add a commit message, select the branch you want to commit to, and select **Commit**. @@ -286,10 +286,10 @@ An example `package.json`: ## Interactive Web Terminals for the Web IDE -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. WARNING: -Interactive Web Terminals for the Web IDE is currently in **Beta**. +Interactive Web Terminals for the Web IDE is currently in [**Beta**](../../../policy/alpha-beta-support.md#beta-features). GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), so you must use your own private runner to make use of this feature. @@ -308,7 +308,7 @@ to work: This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. - If you are using a reverse proxy with your GitLab instance, web terminals must be - [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE SELF)** + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). If you have the terminal open and the job has finished with its tasks, the terminal blocks the job from finishing for the duration configured in @@ -391,7 +391,7 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab Ultimate 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) from GitLab Ultimate to GitLab Free in 13.1. File changes in the Web IDE can be synced to a running web terminal. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 2c499af123c..37f2ef8fc6a 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -7,7 +7,7 @@ type: reference, how-to # Group wikis **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in GitLab 13.5. If you use GitLab groups to manage multiple projects, some of your documentation might span multiple groups. You can create group wikis, instead of [project wikis](index.md), @@ -17,7 +17,7 @@ Group wikis are similar to [project wikis](index.md), with a few limitations: - [Git LFS](../../../topics/git/lfs/index.md) is not supported. - Group wikis are not included in [global search](../../search/advanced_search.md). - Changes to group wikis don't show up in the [group's activity feed](../../group/index.md#group-activity-analytics). -- Group wikis are enabled by default for **(PREMIUM)** and higher tiers. +- Group wikis are enabled by default for GitLab Premium and higher tiers. You [can't turn them off from the GitLab user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/208413). For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). @@ -38,7 +38,7 @@ To access a group wiki: ## Export a group wiki -> Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9. Users with the Owner role in a group can [import and export group wikis](../../group/settings/import_export.md) when importing diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 9cfcaf4ee81..19e77d18aca 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -68,9 +68,8 @@ If you're an instance administrator, you can administer all project topics from To create a project in GitLab: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. -1. On the **New project** page, choose if you want to: +1. On the top bar, select **Menu > Project > Create new project**. +1. On the **Create new project** page, choose if you want to: - Create a [blank project](#create-a-blank-project). - Create a project from a: - [built-in template](#create-a-project-from-a-built-in-template). @@ -80,21 +79,20 @@ To create a project in GitLab: from a different repository. Contact your GitLab administrator if this option is not available. - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). -NOTE: -For a list of words that can't be used as project names see +- For a list of words that you cannot use as project names, see [reserved project and group names](../../user/reserved_names.md). +- For a list of characters that you cannot use in project and group names, see +[limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). ## Create a blank project To create a blank project: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -121,17 +119,15 @@ Anyone can contribute a built-in template by following [these steps](https://abo To create a project from a built-in template: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -149,17 +145,15 @@ Custom project templates are available at: - The [instance-level](../../user/admin_area/custom_project_templates.md) - The [group-level](../../user/group/custom_project_templates.md) -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -177,17 +171,15 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service To create a project from the HIPAA Audit Protocol template: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: - To view a preview of the template, select **Preview**. - To use the template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -196,7 +188,7 @@ To create a project from the HIPAA Audit Protocol template: change the **Visibility Level**. 1. Select **Create project**. -## Push to create a new project +## Create a new project with Git push > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. @@ -218,7 +210,7 @@ Prerequisites: [added to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the top bar, select **Menu > Project**. + 1. On the top bar, select **Menu > Projects**. 1. Select **Groups**. 1. Select a group. 1. Confirm that **New project** is visible in the upper right @@ -266,14 +258,14 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. In the upper right corner of the page, select **Star**. ## View starred projects -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Starred projects**. 1. GitLab displays information about your starred projects, including: @@ -290,33 +282,33 @@ you can [enable delayed project removal](../group/index.md#enable-delayed-projec To delete a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. -1. Select **Delete project** +1. Select **Delete project**. 1. Confirm this action by completing the field. -## Projects pending deletion **(PREMIUM)** +## View 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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) in GitLab 14.9. [Feature flag `project_owners_list_project_pending_deletion`](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) removed. When delayed project deletion is [enabled for a group](../group/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: +projects within that group are not deleted immediately, but only after a delay. + +To view a list of all projects that are pending deletion: 1. On the top bar, select **Menu > Projects > Explore projects**. -1. Select the **Pending deletion** tab (in GitLab 14.6 and later) or the **Deleted projects** tab (GitLab 14.5 and earlier). +1. Based on your GitLab version: + - GitLab 14.6 and later: select the **Pending deletion** tab. + - GitLab 14.5 and earlier: select the **Deleted projects** tab. -Listed for each project is: +Each project in the list shows: - The time the project was marked for deletion. - The time the project is scheduled for final deletion. @@ -326,7 +318,7 @@ Listed for each project is: To view the activity of a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. On the left sidebar, select **Project information > Activity**. @@ -334,12 +326,12 @@ To view the activity of a project: ## Leave a project -If you leave a project you are no longer a project +If you leave a project, you are no longer a project member and cannot contribute. To leave a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. Select **Leave project**. The **Leave project** option only displays @@ -481,3 +473,4 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - [Fork a project](repository/forking_workflow.md#creating-a-fork). - [Adjust project visibility and access levels](settings/index.md#sharing-and-permissions). +- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) |
