diff options
Diffstat (limited to 'doc/user/project')
106 files changed, 1740 insertions, 825 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index d54edc7e6d3..9ca11d43864 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -56,11 +56,18 @@ To add this badge to a project: ## Group badges -Badges can be added to a group and are visible on every project's -overview page that's under that group. In this case, they cannot be edited or -deleted on the project level. If you need to have individual badges for each -project, consider adding them on the [project level](#project-badges) or use -[placeholders](#placeholders). +By adding a badge to a group, you add and enforce a project-level badge +for all projects in the group. The group badge is visible on the **Overview** +page of any project that belongs to the group. + +NOTE: +While these badges appear as project-level badges in the codebase, they +cannot be edited or deleted at the project level. + +If you need individual badges for each project, either: + +- Add the badge at the [project level](#project-badges). +- Use [placeholders](#placeholders). To add a new badge to a group: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 6d1fb0f6755..77cf04cc7eb 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -69,10 +69,14 @@ can easily notice them.  -### Advanced traffic control with Canary Ingress +### 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. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 0db0f14b633..e03e5b10236 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,12 +4,13 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect EKS clusters through cluster certificates **(FREE)** +# Connect EKS clusters through cluster certificates (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -Use [Infrastrucure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +This feature was deprecated in GitLab 14.5. Use [Infrastrucure 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 @@ -20,18 +21,10 @@ Kubernetes Service (EKS). If you already have an EKS cluster and want to connect it to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). -Alternatively, you can [connect them with cluster certificates](add_existing_cluster.md), -although this method is not recommended for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - ## 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). -Alternatively, you can [create new EKS clusters using cluster certificates](#how-to-create-a-new-cluster-on-eks-through-cluster-certificates-deprecated). -Although still available on the GitLab UI, this method was deprecated -in GitLab 14.0 and is scheduled for removal in GitLab 15.0. -It also has [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 3347ef9a437..fcf2583d3ab 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,16 +4,17 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect existing clusters through cluster certificates +# Connect existing clusters through cluster certificates **(DEPRECATED)** -If you have an existing Kubernetes cluster, you can add it to a project, group, -or instance and benefit from the integration with GitLab. +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -The process described on this page uses cluster certificates to connect your cluster -to GitLab. Although this method still works, it is **no longer recommended**. -To connect your cluster to GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) -instead. **(PREMIUM)** +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 Kubernetes Agent](../../clusters/agent/index.md) +instead. + +If you have an existing Kubernetes cluster, you can add it to a project, group, +or instance and benefit from the integration with GitLab. ## Prerequisites diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 0d35e89a560..30be319f2df 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,9 +4,12 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect GKE clusters through cluster certificates **(FREE)** +# Connect GKE clusters through cluster certificates (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. Use [Infrastrucure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) to create a cluster hosted on Google Kubernetes Engine (GKE). @@ -18,21 +21,13 @@ hosted on Google Kubernetes Engine (GKE). If you already have a GKE cluster and want to connect it to GitLab, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). -Alternatively, you can [connect them with cluster certificates](add_existing_cluster.md), -altough this method is not recommended for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - ## Create a new GKE cluster from GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25925) in GitLab 12.4, all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). To create a new GKE cluster from GitLab, use [Infrastructure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md). -Alternatively, you can [create new GKE clusters using cluster certificates](#create-a-new-cluster-on-gke-through-cluster-certificates-deprecated). -Although still available in the GitLab UI, this method was deprecated -in GitLab 14.0 and is scheduled for removal in GitLab 15.0. -It also has [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). - -## Create a new cluster on GKE through cluster certificates (DEPRECATED) +## Create a new cluster on GKE through cluster certificates > [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 4f2bc5526e0..49708e3b6aa 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Creating a new cluster through cluster certificates -is deprecated and no longer recommended. To create a new cluster use -[Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +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). NOTE: Every new Google Cloud Platform (GCP) account receives diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 452f5727620..510aad821cf 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -4,9 +4,15 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster access controls (RBAC or ABAC) +# Access controls with cluster certificates (RBAC or ABAC) (DEPRECATED) **(FREE)** -> Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. +> - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +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 Kubernetes 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 54141fe1103..c3a71ec8585 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,13 +4,14 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy to a Kubernetes cluster with cluster certificates +# Deploy to a Kubernetes cluster with cluster certificates (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -The process described on this page uses cluster certificates to deploy to your cluster -from GitLab. Although this method still works, it is **no longer recommended**. -To deploy to your cluster from GitLab, we **recommend** using the [GitLab Kubernetes Agent](../../clusters/agent/index.md) -instead. **(PREMIUM)** +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 Kubernetes Agent](../../clusters/agent/index.md). +To deploy with the Agent, use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md). A Kubernetes cluster can be the destination for a deployment job. If @@ -77,7 +78,7 @@ You can customize the deployment namespace in a few ways: - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, but the user is responsible for ensuring its existence. You can fully customize this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments) + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments-deprecated) in `.gitlab-ci.yml`. When you customize the namespace, existing environments remain linked to their current @@ -100,7 +101,7 @@ combined with *one* of the following: > Introduced in GitLab 8.15. -The Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) +The Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals-deprecated) support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new shell session in your existing containers. To use this integration, you diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 77921ec1dff..ad378be2d9a 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -4,10 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab-managed clusters +# GitLab-managed clusters (DEPRECATED) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +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 Kubernetes 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 is managed by GitLab, resources for your projects are automatically created. See diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index ac59f874244..c16c6446acd 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,19 +4,22 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project-level Kubernetes clusters **(FREE)** +# Project-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -[Project-level Kubernetes clusters](../../infrastructure/clusters/connect/index.md#cluster-levels) +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 Kubernetes 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. You can also [connect multiple clusters](multiple_kubernetes_clusters.md) to a single project. -After connecting a cluster to GitLab, you can benefit from the large number of -[GitLab features available for Kubernetes clusters](../../infrastructure/clusters/index.md) to manage and deploy to your cluster. - ## View your project-level clusters To view project-level Kubernetes clusters: diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index eb0e8d0e91c..19166a1ff8c 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -4,10 +4,14 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Kubernetes Logs **(FREE)** +# Kubernetes Logs (DEPRECATED) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index e2eae011b8c..540907bf915 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -4,10 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Multiple Kubernetes clusters for a single project +# Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +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 Kubernetes 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 5e4df6009f0..c005ce64bb5 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -6,6 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Host Security **(FREE)** +NOTE: +In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). +You can continue using Container Host Security, even though it relies on this certificate-based +method. The work to allow all aspects of Container Host Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350). + Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can monitor and (optionally) block activity inside the containers themselves. This is done by leveraging an integration with Falco to provide the monitoring capabilities and an integration with Pod 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 3daa48e1811..eb15675da19 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -6,6 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Network Security **(FREE)** +NOTE: +In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). +You can continue using Container Network Security, even though it relies on this certificate-based +method. The work to allow all aspects of Container Network Security to function through the [GitLab Kubernetes Agent](../../../../clusters/agent/index.md) +instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) and [this GitLab Epic](https://gitlab.com/groups/gitlab-org/-/epics/7057). + Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods inside the cluster. Container Network Security can be used to enforce L3, L4, and L7 policies and diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 6eafb4530d3..06fa18d80c9 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -434,11 +434,11 @@ To test the application you deployed, please go to the build log and follow the 1. Click on "Show complete raw" on the upper right-hand corner: -  +  1. Look for HelloWorldApi – API Gateway endpoint similar to shown below: -  +  1. Use curl to test the API. For example: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 7d51fb59793..c138dc64d19 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -84,6 +84,10 @@ so that their members also become eligible Code Owners. If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval of the merge request becomes optional. +Inviting **Subgroup Y** to a parent group of **Project A** +[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as +Code Owners, add this group directly to the project itself. + ### Add a group as a Code Owner To set a group as a Code Owner: diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 6e2635b89f0..15490ab0b94 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy boards **(FREE)** +# 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. @@ -15,6 +15,12 @@ type: howto, reference > - In GitLab 13.11 and earlier, environments in folders do not show deploy boards. > This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in > GitLab 13.12. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. + +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). 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/index.md b/doc/user/project/deploy_keys/index.md index 61dccf1cb1b..c5950347ae9 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -81,10 +81,11 @@ help you access a repository, but there are some notables differences between th [Project maintainers and owners](../../permissions.md#project-members-permissions) can add or enable a deploy key for a project repository: -1. Navigate to the project's **Settings > Repository** page. -1. Expand the **Deploy keys** section. +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) Check **Grant write permissions to this key** to allow `read-write` access. Leave it unchecked for `read-only` access. +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: @@ -164,9 +165,10 @@ configuration. [Project maintainers and owners](../../permissions.md#project-members-permissions) can remove or disable a deploy key for a project repository: -1. Navigate to the project's **Settings > Repository** page. -1. Expand the **Deploy keys** section. -1. Select the **{remove}** or **{cancel}** button. +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. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 483de3b21bd..c840f6c8698 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -29,14 +29,15 @@ You can create as many deploy tokens as you need from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). 1. Sign in to your GitLab account. -1. Go to the project (or group) you want to create deploy tokens for. -1. Go to **Settings > Repository**. -1. Expand the **Deploy tokens** section. -1. Choose a name, expiry date (optional), and username (optional) for the token. +1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy tokens**. +1. Choose a name, and optionally, an expiration date and username for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Select **Create deploy token**. -1. Save the deploy token somewhere safe. After you leave or refresh - the page, **you can't access it again**. + +Save the deploy token somewhere safe. After you leave or refresh +the page, **you can't access it again**.  @@ -46,8 +47,12 @@ Deploy tokens expire at midnight UTC on the date you define. ## Revoking a deploy token -To revoke a deploy token, under the **Active deploy tokens** area, -select the respective **Revoke** button. +To revoke a deploy token: + +1. On the top bar, select **Menu > Projects** or **Menu > Groups** to find your project or group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy tokens**. +1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. ## Limiting scopes of a deploy token diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index db8c6f24063..10dcbddac17 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -212,20 +212,21 @@ requests that modify locked files. Unlock the file to allow changes. To lock a file: 1. Open the file or directory in GitLab. -1. Click the **Lock** button, located near the Web IDE button. +1. On the top right, above the file, select **Lock**. +1. On the confirmation dialog box, select **OK**. -  +If you do not have permission to lock the file, the button is not enabled. -An **Unlock** button is displayed if the file is already locked, and -is disabled if you do not have permission to unlock the file. - -If you did not lock the file, hovering your cursor over the button shows -who locked the file. +To view the user who locked the file (if it was not you), hover over the button. ### View and remove existing locks -The **Locked Files**, accessed from **Project > Repository** left menu, lists -all file and directory locks. Locks can be removed by their author, or any user -with the [Maintainer role](../permissions.md) and above. +To view and remove file locks: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Locked Files**. This list shows all the files locked either through LFS or GitLab UI. + +Locks can be removed by their author, or any user +with at least the [Maintainer role](../permissions.md). diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png Binary files differdeleted file mode 100644 index e881442630b..00000000000 --- a/doc/user/project/img/file_lock.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index cda018a0c37..0c50fc77e33 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -52,20 +52,18 @@ namespace that started the import process. ## Import your Bitbucket repositories -1. Sign in to GitLab and go to your dashboard. -1. Click on **New project**. - -1. Click on the "Bitbucket Cloud" button. - -  - -1. Grant GitLab access to your Bitbucket account +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **Bitbucket Cloud**. +1. Log in to Bitbucket and grant GitLab access to your Bitbucket account.  -1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which - each project will be imported. +1. Select the projects that you'd like to import or import all projects. + You can filter projects by name and select the namespace + each project will be imported for.  diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 2715804b37a..81e7d159a06 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -78,10 +78,7 @@ the author's: - `slug` - `displayName` -If the user is not found by any of these properties, the search falls back to the author's -`email` address. - -Alternatively, if there is also no email address, the project creator is set as the author. +If the user is not found by any of these properties, the project creator is set as the author. ##### Enable or disable User assignment by username @@ -104,22 +101,27 @@ Feature.disable(:bitbucket_server_user_mapping_by_username) ## Import your Bitbucket repositories -1. Sign in to GitLab and go to your dashboard. -1. Click on **New project**. -1. Click on the "Bitbucket Server" button. If the button is not present, enable the importer in - **Admin > Application Settings > Visibility and access controls > Import sources**. +Prerequisite: -  +- An administrator must have enabled the importer in + **Admin > Application Settings > Visibility and access controls > Import sources**. -1. Enter your Bitbucket Server credentials. +To import your Bitbucket repositories: -  +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **Bitbucket Server**. +1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. +1. Select the projects that you'd like to import or import all projects. + You can filter projects by name and select the namespace + each project will be imported for. -1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which each project is - imported. +## Automate group and project import **(PREMIUM)** -  +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). ## Troubleshooting diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 982bc6d90e8..3458c7fe4a7 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -16,15 +16,16 @@ users. To import your project from FogBugz: -1. From your GitLab dashboard, select **New project**. -1. Select the **FogBugz** button. -  +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **FogBugz**. 1. Enter your FogBugz URL, email address, and password. -  1. Create a mapping from FogBugz users to GitLab users.  -1. Select **Import** for the projects you want to import. +1. For the projects you want to import, select **Import**.  -1. After the import finishes, click the link to go to the project +1. After the import finishes, select the link to go to the project dashboard. Follow the directions to push your existing repository.  diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 3bbc70b4337..db55330f806 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -38,8 +38,6 @@ that started the import process. The importer page is visible when you create a new project. - - Select the **Gitea** link to start the import authorization process.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eff733b0b3d..e1a81ae1bba 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -25,6 +25,7 @@ The following aspects of a project are imported: - Pull request "merged by" information (GitLab.com & 13.7+) - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) +- Pull request comments replies in discussions ([GitLab.com & 14.5+](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)) References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -67,7 +68,7 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) that matches their GitLab account's email address. NOTE: @@ -240,3 +241,8 @@ To disable the feature, run this command: # Disable Feature.disable(:github_importer_lower_per_page_limit, group) ``` + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index f25b29317a7..bcbc6e09f1b 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -26,3 +26,8 @@ for permission to access your projects. After accepting, you are automatically r To import a project, click "Import". The importer imports your repository and issues. Once the importer is done, a new GitLab project is created with your imported data. + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/import/img/bitbucket_server_import_credentials.png b/doc/user/project/import/img/bitbucket_server_import_credentials.png Binary files differdeleted file mode 100644 index 25bcc3ab6e6..00000000000 --- a/doc/user/project/import/img/bitbucket_server_import_credentials.png +++ /dev/null diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png Binary files differdeleted file mode 100644 index 3f94dd83dd6..00000000000 --- a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/img/fogbugz_import_login.png b/doc/user/project/import/img/fogbugz_import_login.png Binary files differdeleted file mode 100644 index 6ba4d443f1a..00000000000 --- a/doc/user/project/import/img/fogbugz_import_login.png +++ /dev/null diff --git a/doc/user/project/import/img/fogbugz_import_select_fogbogz.png b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png Binary files differdeleted file mode 100644 index d207646a6f2..00000000000 --- a/doc/user/project/import/img/fogbugz_import_select_fogbogz.png +++ /dev/null diff --git a/doc/user/project/import/img/import_projects_from_new_project_page.png b/doc/user/project/import/img/import_projects_from_new_project_page.png Binary files differdeleted file mode 100644 index 7c32d3555d1..00000000000 --- a/doc/user/project/import/img/import_projects_from_new_project_page.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 887eb546148..6e02a9bf5ab 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -102,3 +102,18 @@ After an administrator creates an alias for a project, you can use the alias to repository. For example, if an administrator creates the alias `gitlab` for the project `https://gitlab.com/gitlab-org/gitlab`, you can clone the project with `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. + +## Automate group and project import **(PREMIUM)** + +The GitLab Professional Services team uses [Congregate](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate) +to orchestrate user, group, and project import API calls. With Congregate, you can migrate data to +GitLab from: + +- Other GitLab instances +- GitHub Enterprise +- GitHub.com +- Bitbucket Server +- Bitbucket Data Center + +See the [Quick Start Guide](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start) +to learn how to use this approach for migrating users, groups, and projects at scale. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index f3843396b79..aa256e07b30 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -61,3 +61,7 @@ creating small and efficient Git pack files. So it might be a good idea to spend time and CPU to properly repack your repository before sending it for the first time to your GitLab server. See [this StackOverflow question](https://stackoverflow.com/questions/28720151/git-gc-aggressive-vs-git-repack/). + +## Related topics + +- [Mirror with Perforce Helix with Git Fusion](../repository/mirror/bidirectional.md#mirror-with-perforce-helix-with-git-fusion) diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index e504f3678a7..0b96238006e 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -23,3 +23,8 @@ You can import your existing repositories by providing the Git URL: <!-- vale gitlab.SubstitutionWarning = YES -->  + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](index.md#automate-group-and-project-import). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index f3173736e9b..78cd2f8fb79 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -47,7 +47,7 @@ Projects include the following [features](https://about.gitlab.com/features/): strategy and get reviewed by your team. - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before implementing a change. - - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. + - [Fix merge conflicts from the UI](merge_requests/conflicts.md): View Git diffs from the GitLab UI. - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results of the changes proposed in a merge request. - [Labels](labels.md): Organize issues and merge requests by labels. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index eaab1933b79..d155f91e40b 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,31 +4,40 @@ 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 --- -# Custom issue tracker service **(FREE)** +# Custom issue tracker **(FREE)** -Use a custom issue tracker that is not in the integration list. +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), +you can enable a custom issue tracker. + +After you enable the custom issue tracker, a link to the issue tracker displays +on the left sidebar in your project. + + + +## Enable a custom issue tracker To enable a custom issue tracker in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: - **Project URL**: The URL to view all the issues in the custom issue tracker. - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`. - GitLab replaces `:id` with the issue number (for example, - `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`). + GitLab replaces `:id` with the issue number (for example, + `https://customissuetracker.com/project-name/:id`, which becomes + `https://customissuetracker.com/project-name/123`). - **New issue URL**: <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> - **This URL is not used and removal is planned in a future release.** - Enter any URL here. - For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). - -1. Select **Save changes** or optionally select **Test settings**. + **This URL is not used and an [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/327503) to remove it.** + Enter any URL. -After you configure and enable the custom issue tracker service, a link appears on the GitLab -project pages. This link takes you to the custom issue tracker. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Reference issues in a custom issue tracker diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3177aaefb75..47a81594ca9 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -37,20 +37,20 @@ Complete these steps in GitLab: 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated on GitHub. 1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. -1. (Optional) To disable static status check names, clear the **Static status check names** checkbox. +1. (Optional) To disable static status check names, clear the **Enable static status check names** checkbox. 1. Select **Save changes** or optionally select **Test settings**. After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. -### Static / dynamic status check names +### Static or dynamic status check names > - Introduced in GitLab 11.5: using static status check names as opt-in option. > - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. This makes it possible to mark these status checks as **Required** on GitHub. -When **Static status check names** is enabled on the integration page, your +When **Enable static status check names** is checked on the integration page, your GitLab instance host name is appended to a status check name. -When disabled, it uses dynamic status check names and appends the branch name. +When unchecked, it uses dynamic status check names and appends the branch name. diff --git a/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png b/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png Binary files differnew file mode 100644 index 00000000000..e316a2acc39 --- /dev/null +++ b/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png diff --git a/doc/user/project/integrations/img/zentao_product_id.png b/doc/user/project/integrations/img/zentao_product_id.png Binary files differnew file mode 100644 index 00000000000..a91b4c3f82d --- /dev/null +++ b/doc/user/project/integrations/img/zentao_product_id.png diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 92e5feefb73..119f219499c 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -54,7 +54,7 @@ Then fill in the integration configuration: To change the bot's username, provide a value. - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want notifications about failed pipelines only. -- **Branches to be notified**: The branches to send notifications for. +- **Branches for which notifications are to be sent**: The branches to send notifications for. - **Labels to be notified**: (Optional) Labels required for the issue or merge request to trigger a notification. Leave blank to notify for all issues and merge requests. - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index fac26f8e70c..6679bab745b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -18,8 +18,8 @@ in Microsoft Teams. To integrate the services, you must: To configure Microsoft Teams to listen for notifications from GitLab: -1. In Microsoft Teams, search for "incoming webhook" in the search bar, and select the - **Incoming Webhook** item: +1. In Microsoft Teams, type `incoming webhook` in the search bar, and select + **Incoming Webhook**:  @@ -34,11 +34,12 @@ To configure Microsoft Teams to listen for notifications from GitLab: After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: -1. Sign in to GitLab as a user with [Administrator](../../permissions.md) and go - to your project's page. -1. Go to **Settings > Integrations** and select **Microsoft Teams Notification**. -1. Select **Active** to enable the integration. -1. Select the checkbox next to each **Trigger** to enable: +1. Sign in to GitLab as an administrator. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Microsoft Teams notifications**. +1. To enable the integration, select **Active**. +1. In the **Trigger** section, select the checkbox next to each event to enable it: - Push - Issue - Confidential issue @@ -46,15 +47,15 @@ GitLab to send the notifications: - Note - Confidential note - Tag push - - Pipeline - If you enable this trigger, you can also select **Notify only broken pipelines** to be notified only about failed pipelines. + - Pipeline - Wiki page 1. In **Webhook**, paste the URL you copied when you [configured Microsoft Teams](#configure-microsoft-teams). -1. (Optional) If you enabled the pipeline trigger, you can select the +1. Optional. If you enable the pipeline trigger, select the **Notify only broken pipelines** checkbox to push notifications only when pipelines break. 1. Select the branches you want to send notifications for. -1. Click **Save changes**. +1. Select **Save changes**. -## Resources +## Related topics - [Setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 2c154467115..819c17c12fd 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -62,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index a38d2157699..d399c7f2901 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -45,7 +45,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. (Optional) In **Username**, enter the username of the Slack bot that sends the notifications. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. -1. In the **Branches to be notified** dropdown, select which types of branches +1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches to send notifications for. 1. Leave the **Labels to be notified** field blank to get all notifications, or add labels that the issue or merge request must have to trigger a diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 814c64d8140..daab24a8ab9 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -21,7 +21,7 @@ In GitLab: 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. -1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. +1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches to send notifications for. 1. Select `Save changes` or optionally select **Test settings**. Your Unify Circuit conversation now starts receiving GitLab event notifications. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 9b07e6322bc..ab70a2d43f4 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -9,31 +9,50 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can configure a [webhook](webhooks.md) in your project that triggers when an event occurs. The following events are supported. +Event type | Trigger +---------------------------------------------|----------------------------------------------------------------------------- +[Push event](#push-events) | A push is made to the repository. +[Tag event](#tag-events) | Tags are created or deleted in the repository. +[Issue event](#issue-events) | A new issue is created or an existing issue is updated, closed, or reopened. +[Comment event](#comment-events) | A new comment is made on commits, merge requests, issues, and code snippets. +[Merge request event](#merge-request-events) | A merge request is created, updated, merged, or closed, or a commit is added in the source branch. +[Wiki page event](#wiki-page-events) | A wiki page is created, updated, or deleted. +[Pipeline event](#pipeline-events) | A pipeline status changes. +[Job event](#job-events) | A job status changes. +[Deployment event](#deployment-events) | A deployment starts, succeeds, fails, or is canceled. +[Group member event](#group-member-events) | A user is added or removed from a group, or a user's access level or access expiration date changes. +[Subgroup event](#subgroup-events) | A subgroup is created or removed from a group. +[Feature flag event](#feature-flag-events) | A feature flag is turned on or off. +[Release event](#release-events) | A release is created or updated. + +NOTE: +If an author has no public email listed in their +[GitLab profile](https://gitlab.com/-/profile), the `email` attribute in the +webhook payload displays a value of `[REDACTED]`. + ## Push events -Triggered when you push to the repository except when pushing tags. +Push events are triggered when you push to the repository, except when: -NOTE: -When more than 20 commits are pushed at once, the `commits` webhook -attribute only contains the newest 20 for performance reasons. Loading -detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. +- You push tags. +- A single push includes changes for more than three branches by default + (depending on the [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)). -NOTE: -If a branch creation push event is generated without new commits being introduced, the -`commits` attribute in the payload is empty. +If you push more than 20 commits at once, the `commits` +attribute in the payload contains information about the newest 20 commits only. +Loading detailed commit data is expensive, so this restriction exists for performance reasons. +The `total_commits_count` attribute contains the actual number of commits. -Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -branches, this hook isn't executed. +If you create and push a branch without any new commits, the +`commits` attribute in the payload is empty. -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Push Hook ``` -**Payload example:** +Payload example: ```json { @@ -111,20 +130,19 @@ X-Gitlab-Event: Push Hook ## Tag events -Triggered when you create (or delete) tags to the repository. +Tag events are triggered when you create or delete tags in the repository. -NOTE: -If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -tags, this hook is not executed. +This hook is not executed if a single push includes changes for more than three +tags by default (depending on the +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)). -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Tag Push Hook ``` -**Payload example:** +Payload example: ```json { @@ -171,22 +189,26 @@ X-Gitlab-Event: Tag Push Hook ## Issue events -Triggered when a new issue is created or an existing issue was updated/closed/reopened. +Issue events are triggered when a new issue is created or +an existing issue is updated, closed, or reopened. -**Request header**: - -```plaintext -X-Gitlab-Event: Issue Hook -``` - -**Available `object_attributes.action`:** +The available values for `object_attributes.action` in the payload are: - `open` - `close` - `reopen` - `update` -**Payload example:** +The `assignee` and `assignee_id` keys are deprecated +and contain the first assignee only. + +Request header: + +```plaintext +X-Gitlab-Event: Issue Hook +``` + +Payload example: ```json { @@ -329,31 +351,31 @@ X-Gitlab-Event: Issue Hook } ``` -NOTE: -`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. - ## Comment events -Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The -payload also includes information about the target of the comment. For example, -a comment on an issue includes the specific issue information under the `issue` key. -Valid target types: +Comment events are triggered when a new comment is made on commits, +merge requests, issues, and code snippets. + +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). +The payload includes information about the target of the comment. For example, +a comment on an issue includes specific issue information under the `issue` key. + +The valid target types are: - `commit` - `merge_request` - `issue` - `snippet` -### Comment on commit +### Comment on a commit -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -428,15 +450,15 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on merge request +### Comment on a merge request -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -558,15 +580,18 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on issue +### Comment on an issue + +- The `assignee_id` field is deprecated and shows the first assignee only. +- The `event_type` is set to `confidential_note` for confidential issues. -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -664,21 +689,15 @@ X-Gitlab-Event: Note Hook } ``` -NOTE: -`assignee_id` field is deprecated and now shows the first assignee only. - -NOTE: -`event_type` is set to `confidential_note` for confidential issues. - -### Comment on code snippet +### Comment on a code snippet -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -749,15 +768,13 @@ X-Gitlab-Event: Note Hook ## Merge request events -Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch. +Merge request events are triggered when: -**Request header**: +- A new merge request is created. +- An existing merge request is updated, approved, unapproved, merged, or closed. +- A commit is added in the source branch. -```plaintext -X-Gitlab-Event: Merge Request Hook -``` - -**Available `object_attributes.action`:** +The available values for `object_attributes.action` in the payload are: - `open` - `close` @@ -767,7 +784,13 @@ X-Gitlab-Event: Merge Request Hook - `unapproved` - `merge` -**Payload example:** +Request header: + +```plaintext +X-Gitlab-Event: Merge Request Hook +``` + +Payload example: ```json { @@ -921,17 +944,17 @@ X-Gitlab-Event: Merge Request Hook } ``` -## Wiki Page events +## Wiki page events -Triggered when a wiki page is created, updated or deleted. +Wiki page events are triggered when a wiki page is created, updated, or deleted. -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Wiki Page Hook ``` -**Payload example**: +Payload example: ```json { @@ -981,18 +1004,18 @@ X-Gitlab-Event: Wiki Page Hook ## Pipeline events +Pipeline events are triggered when the status of a pipeline changes. + In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) and later, the pipeline webhook returns only the latest jobs. -Triggered on status change of Pipeline. - -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Pipeline Hook ``` -**Payload example**: +Payload example: ```json { @@ -1233,15 +1256,17 @@ X-Gitlab-Event: Pipeline Hook ## Job events -Triggered on status change of a job. +Job events are triggered when the status of a job changes. + +The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit. -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Job Hook ``` -**Payload example**: +Payload example: ```json { @@ -1303,24 +1328,24 @@ X-Gitlab-Event: Job Hook } ``` -Note that `commit.id` is the ID of the pipeline, not the ID of the commit. - ## Deployment events -Triggered when a deployment: +Deployment events are triggered when a deployment: -- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) +- Starts ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5) - Succeeds - Fails - Is cancelled -**Request Header**: +The `deployable_id` in the payload is the ID of the CI/CD job. + +Request header: ```plaintext X-Gitlab-Event: Deployment Hook ``` -**Payload example**: +Payload example: ```json { @@ -1363,28 +1388,26 @@ X-Gitlab-Event: Deployment Hook } ``` -Note that `deployable_id` is the ID of the CI job. - ## Group member events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. Member events are triggered when: -- A user is added as a group member -- The access level of a user has changed -- The expiration date for user access has been updated -- A user has been removed from the group +- A user is added as a group member. +- The access level of a user changes. +- The expiration date for user access is updated. +- A user is removed from the group. ### Add member to group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1406,13 +1429,13 @@ X-Gitlab-Event: Member Hook ### Update member access level or expiration date -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1434,13 +1457,13 @@ X-Gitlab-Event: Member Hook ### Remove member from group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1466,18 +1489,18 @@ X-Gitlab-Event: Member Hook Subgroup events are triggered when: -- A [subgroup is created in a group](#subgroup-created-in-a-group) -- A [subgroup is removed from a group](#subgroup-removed-from-a-group) +- A [subgroup is created in a group](#create-a-subgroup-in-a-group). +- A [subgroup is removed from a group](#remove-a-subgroup-from-a-group). -### Subgroup created in a group +### Create a subgroup in a group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Subgroup Hook ``` -**Payload example**: +Payload example: ```json { @@ -1497,15 +1520,17 @@ X-Gitlab-Event: Subgroup Hook } ``` -### Subgroup removed from a group +### Remove a subgroup from a group -**Request Header**: +This webhook is not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group). + +Request header: ```plaintext X-Gitlab-Event: Subgroup Hook ``` -**Payload example**: +Payload example: ```json { @@ -1525,20 +1550,17 @@ X-Gitlab-Event: Subgroup Hook } ``` -NOTE: -Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) +## Feature flag events -## Feature Flag events +Feature flag events are triggered when a feature flag is turned on or off. -Triggered when a feature flag is turned on or off. - -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Feature Flag Hook ``` -**Payload example**: +Payload example: ```json { @@ -1580,20 +1602,20 @@ X-Gitlab-Event: Feature Flag Hook ## Release events -Triggered when a release is created or updated. +Release events are triggered when a release is created or updated. -**Request Header**: +The available values for `object_attributes.action` in the payload are: + +- `create` +- `update` + +Request header: ```plaintext X-Gitlab-Event: Release Hook ``` -**Available `object_attributes.action`:** - -- `create` -- `update` - -**Payload example**: +Payload example: ```json { diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 0891d48c038..e0405955d3d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -40,8 +40,14 @@ including: ## Group webhooks **(PREMIUM)** -You can configure a webhook for a group to ensure all projects in the group -receive the same webhook settings. +You can configure a group webhook, which is triggered by events +that occur across all projects in the group. + +Group webhooks can also be configured to listen for events that are +specific to a group, including: + +- [Group member events](webhook_events.md#group-member-events) +- [Subgroup events](webhook_events.md#subgroup-events) ## Configure a webhook diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..67125c3ebbf --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,42 @@ +--- +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 +--- + +# ZenTao product integration **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. + +[ZenTao](https://www.zentao.net/) is a web-based project management platform. + +## Configure ZenTao + +This integration requires a ZenTao API secret key. + +Complete these steps in ZenTao: + +1. Go to your **Admin** page and select **Develop > Application**. +1. Select **Add Application**. +1. Under **Name** and **Code**, enter a name and a code for the new secret key. +1. Under **Account**, select an existing account name. +1. Select **Save**. +1. Copy the generated key to use in GitLab. + +## Configure GitLab + +Complete these steps in GitLab: + +1. Go to your project and select **Settings > Integrations**. +1. Select **ZenTao**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the ZenTao configuration information: + - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). + - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. + - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). + - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. + +  + +1. To verify the ZenTao connection is working, select **Test settings**. +1. Select **Save changes**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 8a599608f71..4c35f007fc7 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -197,21 +197,22 @@ card includes: Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the issue board feature to create or delete lists. They can also drag issues from one list to another. -## How GitLab orders issues in a list - -When visiting a board, issues appear ordered in any list. You're able to change -that order by dragging the issues. The changed order is saved, so that anybody who visits the same -board later sees the reordering, with some exceptions. +## Ordering issues in a list When an issue is created, the system assigns a relative order value that is greater than the maximum value of that issue's project or root group. This means the issue will be at the bottom of any issue list that it appears in. +When you visit a board, issues appear ordered in any list. You're able to change +that order by dragging the issues. The changed order is saved, so that anybody who visits the same +board later sees the reordering, with some exceptions. + Any time you drag and reorder the issue, its relative order value changes accordingly. Then, any time that issue appears in any board, the ordering is done according to the updated relative order value. If a user in your GitLab instance drags issue `A` above issue `B`, the ordering is maintained when these two issues are subsequently -loaded in any board in the same instance. This could be a different project board or a different group +loaded in any board in the same instance. +This could be a different project board or a different group board, for example. This ordering also affects [issue lists](issues/sorting_issue_lists.md). @@ -593,7 +594,7 @@ You can move issues and lists by dragging them. Prerequisites: -- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab. +- You must have at least the Reporter [role](../permissions.md#project-members-permissions) for a project in GitLab. To move an issue, select the issue card and drag it to another position in its current list or into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index e020bdee737..aba8c45699c 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -25,7 +25,7 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid /zoom https://zoom.us/j/123456789 ``` -If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), +If the Zoom meeting URL is valid and you have at least the Reporter [role](../../permissions.md), a system alert notifies you of its successful addition. The issue's description is automatically edited to include the Zoom link, and a button appears right under the issue's title. @@ -44,5 +44,5 @@ Similarly to adding a Zoom meeting, you can remove it with a quick action: /remove_zoom ``` -If you have at least [Reporter permissions](../../permissions.md), +If you have at least the Reporter [role](../../permissions.md), a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 136e8ee2ebb..b8a01f7ccd6 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -77,14 +77,14 @@ that prevent leaks of private data. There are two kinds of level access for confidential issues. The general rule is that confidential issues are visible only to members of a project with at -least [Reporter access](../../permissions.md#project-members-permissions). However, a guest user can also create +least the Reporter [role](../../permissions.md#project-members-permissions). However, a guest user can also create confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with the [Maintainer role](../../permissions.md) and Guest access +For example, here's what a user with the [Maintainer role](../../permissions.md) and the Guest role sees in the project's search results respectively. -| Maintainer role | Guest access | +| Maintainer role | Guest role | |:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 94a5fdc3f0f..2c20ccdcee0 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Due dates **(FREE)** Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are -shipped on time. Users need at least [Reporter permissions](../../permissions.md) +shipped on time. Users need at least the Reporter [role](../../permissions.md) to be able to edit the due date. All users with permission to view the issue can view the due date. diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 9842b0820e6..64838b261ce 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -49,3 +49,4 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) - [Parts of an issue](issue_data_and_actions.md) +- [Tasks](../../tasks.md) diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a2fa044be6b..6b3d5d6563a 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -380,12 +380,18 @@ You can also use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a comment or description field. -## Real-time sidebar **(FREE SELF)** +## Real-time sidebar -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. +> - [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. -Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable it, you need to enable [Action Cable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). +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. + +Assignees in the sidebar are updated in real time. ## Similar issues diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index aed346fb504..ebfc723280f 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -8,34 +8,59 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can sort a list of issues several ways, including by: -- Blocking **(PREMIUM)** -- Created date -- Due date -- Label priority -- Last updated -- Milestone due date -- Popularity -- Priority -- Title ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3) -- Weight +- [Blocking issues](#sorting-by-blocking-issues) +- [Created date](#sorting-by-created-date) +- [Due date](#sorting-by-due-date) +- [Label priority](#sorting-by-label-priority) +- [Last updated](#sorting-by-last-updated) +- [Manual sorting](#manual-sorting) +- [Milestone due date](#sorting-by-milestone-due-date) +- [Popularity](#sorting-by-popularity) +- [Priority](#sorting-by-priority) +- [Title](#sorting-by-title) +- [Weight](#sorting-by-weight) The available sorting options can change based on the context of the list. -For sorting by issue priority, see [Label Priority](../labels.md#label-priority). -In group and project issue lists, it is also possible to order issues manually, -similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). +## Sorting by blocking issues **(PREMIUM)** -## Sorting by popularity +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. -When you select sorting by **Popularity**, the issue order changes to sort descending by the -number of upvotes ([awarded](../../award_emojis.md) "thumbs up" emoji) -on each issue. You can use this to identify issues that are in high demand. +When you sort by **Blocking**, the issue list changes to sort descending by the +number of issues each issue is blocking. + +## Sorting by created date + +When you sort by **Created date**, the issue list changes to sort descending by the issue +creation date. Issues created most recently are first. + +## Sorting by due date + +When you sort by **Due date**, the issue list changes to sort ascending by the issue +[due date](issue_data_and_actions.md#due-date). Issues with the earliest due date are first, +and issues without a due date are last. + +## Sorting by label priority + +When you sort by **Label priority**, the issue list changes to sort descending. +Issues with the highest priority label are first, then all other issues. + +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. + +## Sorting by last updated + +When you sort by **Last updated**, the issue list changes to sort by the time of a last +update. Issues changed the most recently are first. ## Manual sorting > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. -When you select **Manual** sorting, you can change +When you sort by **Manual** order, you can change the order by dragging and dropping the issues. The changed order persists, and everyone who visits the same list sees the updated issue order, with some exceptions. @@ -48,13 +73,47 @@ the updated relative order value is used for the ordering. So, if anyone drags issue `A` above issue `B` in your GitLab instance, this ordering is maintained whenever they appear together in any list. -This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). +This ordering also affects [issue boards](../issue_board.md#ordering-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, -and vice versa. +and the other way around. -## Sorting by blocking issues **(PREMIUM)** +## Sorting by milestone due date -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. +When you sort by **Milestone due date**, the issue list changes to sort ascending by the +assigned milestone due date. Issues with milestones with the earliest due date are first, +then issues with a milestone without a due date. + +## Sorting by popularity + +When you sort by **Popularity**, the issue order changes to sort descending by the +number of upvotes ([awarded](../../award_emojis.md) a "thumbs up" emoji) +on each issue. You can use this to identify issues that are in high demand. + +## Sorting by priority + +When you sort by **Priority**, the issue order changes to sort in this order: + +1. Issues with milestones that have due dates, where the soonest assigned milestone is listed first. +1. Issues with milestones with no due dates. +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. + +## Sorting by title + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3. + +When you sort by **Title**, the issue order changes to sort alphabetically by the issue +title in this order: + +- Emoji +- Special characters +- Numbers +- Letters: first Latin, then accented (for example, `ö`) + +## Sorting by weight -When you select to sort by **Blocking**, the issue list changes to sort descending by the -number of issues each issue is blocking. You can use this to determine the critical path for your backlog. +When you sort by **Weight**, the issue list changes to sort ascending by the +[issue weight](issue_weight.md). +Issues with lowest weight are first, and issues without a weight are last. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index f9788ef18ec..adf0a115c6e 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -120,8 +120,8 @@ To remove a member from a project: 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 - user has not forked the private repository. Existing forks continue to receive - changes from the upstream project. You may also want to configure your project + user has not forked the private repository or created webhooks. Existing forks continue to receive + changes from the upstream project, and webhooks continue to receive updates. You may also want to configure your project to prevent projects in a group [from being forked outside their group](../../group/index.md#prevent-project-forking-outside-group). 1. Select **Remove member**. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 2bc6d5bb148..8f803f9207c 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -21,6 +21,9 @@ measuring the accessibility of web sites, and has built a simple This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. +From [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), the version of `pa11y` uses +[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1), which may report more issues. + ## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index aff55419a88..d873f715557 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -3,7 +3,7 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html' --- # Merge request approvals **(FREE)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index b422982c0e7..1249aa826fa 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -167,7 +167,7 @@ for protected branches. **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. -You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +You may have to grant users with the Reporter [role](../../../permissions.md#project-members-permissions) permission to approve merge requests before they can merge to a protected branch. Some users (like managers) may not need permission to push or merge code, but still need oversight on proposed work. To enable approval permissions for these users without diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1c56e91ed6b..56e93741c1a 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -39,7 +39,7 @@ By default, the author of a merge request cannot approve it. To change this sett 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Clear the **Prevent MR approval by the author** checkbox. +1. Clear the **Prevent approval by author** checkbox. 1. Select **Save changes**. Authors can edit the approval rule in an individual merge request and override @@ -64,14 +64,20 @@ their own. To do this: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent MR approvals from users who make commits to the MR** checkbox. +1. Select the **Prevent approvals by users who add commits** checkbox. If this checkbox is cleared, an administrator has disabled it [at the instance level](../../../admin_area/merge_requests_approvals.md), and it can't be changed at the project level. 1. Select **Save changes**. -Even with this configuration, [code owners](../../code_owners.md) who contribute -to a merge request can approve merge requests that affect files they own. +Depending on your version of GitLab, [code owners](../../code_owners.md) who commit +to a merge request may or may not be able to approve the work: + +- In GitLab 13.10 and earlier, [code owners](../../code_owners.md) who commit + to a merge request can approve it, even if the merge request affects files they own. +- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/331548), + [code owners](../../code_owners.md) who commit + to a merge request cannot approve it, when the merge request affects files they own. To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), read the official Git documentation for an explanation. @@ -84,7 +90,7 @@ on merge requests, you can disable this setting: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. +1. Select the **Prevent editing approval rules in merge requests** checkbox. 1. Select **Save changes**. This change affects all open merge requests. @@ -102,7 +108,7 @@ permission enables an electronic signature for approvals, such as the one define [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Require user password for approvals** checkbox. +1. Select the **Require user password to approve** checkbox. 1. Select **Save changes**. ## Remove all approvals when commits are added to the source branch @@ -113,7 +119,7 @@ when more changes are added to it: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Require new approvals when new commits are added to an MR** checkbox. +1. Select the **Remove all approvals when commits are added to the source branch** checkbox. 1. Select **Save changes**. Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) @@ -133,21 +139,23 @@ coverage. To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). -## Merge request approval settings cascading +## Settings cascading -> [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. +> - [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 not available. To make it available per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md). On GitLab.com, this feature is not available. -You should not use this feature for production environments +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. You can also enforce merge request approval settings: -- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all - projects. -- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups and projects. +- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups + on an instance and, therefore, all projects. +- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups + and projects. -If the settings are inherited by a group or project, they cannot be overridden by the group or project that inherited them. +If the settings are inherited by a group or project, they cannot be changed in the group or project +that inherited them. ## Related links diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 339f67f828f..4ae59a76a9a 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -40,7 +40,7 @@ protected branch. ## Forking workflow With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular -developers get Reporter access to the authoritative repository, which prohibits +developers get the Reporter role on the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index e9f1874eb96..9bfbbd8fc6f 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -343,8 +343,7 @@ It's possible to have a custom tool provide Code Quality reports in GitLab. To do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the - [Code Quality report - artifact](../../../ci/yaml/index.md#artifactsreportscodequality). + [Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md new file mode 100644 index 00000000000..b615c86288c --- /dev/null +++ b/doc/user/project/merge_requests/commit_templates.md @@ -0,0 +1,51 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, howto +--- + +# Commit message templates **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. + +## Merge commit message template + +As a project maintainer, you're able to configure merge commit message template. It will be used during merge to +create commit message. Template uses similar syntax to +[review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + +Default merge commit message can be recreated using following template: + +```plaintext +Merge branch '%{source_branch}' into '%{target_branch}' + +%{title} + +%{issues} + +See merge request %{reference} +``` + +This commit message can be customized to follow any guidelines you might have. +To do so, expand the **Merge requests** tab within your project's **General** +settings and change the **Merge commit message template** text: + + + +You can use static text and following variables: + +| Variable | Description | Output example | +|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| `%{source_branch}` | The name of the branch that is being merged. | `my-feature-branch` | +| `%{target_branch}` | The name of the branch that the changes are applied to. | `master` | +| `%{title}` | Title of the merge request. | Fix stuff | +| `%{issues}` | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400` | +| `%{description}` | Description of the merge request. | Merge request description.<br>Can be multiline. | +| `%{reference}` | Reference to the merge request. | group-name/project-name!72359 | + +NOTE: +Empty variables that are the only word in a line will be removed along with all newline characters preceding it. + +Merge commit template field has a limit of 500 characters. This limit only applies to the template +itself. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md new file mode 100644 index 00000000000..dc128f89fcd --- /dev/null +++ b/doc/user/project/merge_requests/conflicts.md @@ -0,0 +1,177 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, concepts +--- + +# Merge conflicts **(FREE)** + +_Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different +changes, and you must decide which change to accept. In a merge request, Git compares +the two versions of the files line by line. In most cases, GitLab can merge changes +together. However, if two branches both change the same lines, GitLab blocks the merge, +and you must choose which change you want to keep. + +A merge request cannot merge until you either: + +- Create a merge commit. +- Resolve the conflict through a rebase. + + + +## Conflicts you can resolve in the user interface + +If your merge conflict meets all of the following conditions, you can resolve the +merge conflict in the GitLab user interface: + +- The file is text, not binary. +- The file is in a UTF-8 compatible encoding. +- The file does not already contain conflict markers. +- The file, with conflict markers added, is less than 200 KB in size. +- The file exists under the same path in both branches. + +If any file in your merge request contains conflicts, but can't meet all of these +criteria, you must resolve the conflict manually. + +## Conflicts GitLab can't detect + +GitLab does not detect conflicts when both branches rename a file to different names. +For example, these changes don't create a conflict: + +1. On branch `a`, doing `git mv example.txt example1.txt` +1. On branch `b`, doing `git mv example1.txt example3.txt`. + +When these branches merge, both `example1.txt` and `example3.txt` are present. + +## Methods of resolving conflicts + +GitLab shows [conflicts available for resolution](#conflicts-you-can-resolve-in-the-user-interface) +in the user interface, and you can also resolve conflicts locally through the command line: + +- [Interactive mode](#resolve-conflicts-in-interactive-mode): UI method best for + conflicts that only require you to select which version of a line to keep, without edits. +- [Inline editor](#resolve-conflicts-in-the-inline-editor): UI method best for more complex conflicts that require you to + edit lines and manually blend changes together. +- [Command line](#resolve-conflicts-from-the-command-line): provides complete control over the most complex conflicts. + +## Resolve conflicts in interactive mode + +To resolve less-complex conflicts from the GitLab user interface: + +1. Go to your merge request. +1. Select **Overview**, and scroll to the merge request reports section. +1. Find the merge conflicts message, and select **Resolve conflicts**. + GitLab shows a list of files with merge conflicts. The conflicts are + highlighted: + +  +1. For each conflict, select **Use ours** or **Use theirs** to mark the version + of the conflicted lines you want to keep. This decision is known as + "resolving the conflict." +1. Enter a **Commit message**. +1. Select **Commit to source branch**. + +Resolving conflicts merges the target branch of the merge request into the +source branch, using the version of the text you chose. If the source branch is +`feature` and the target branch is `main`, these actions are similar to running +`git checkout feature; git merge main` locally. + +## Resolve conflicts in the inline editor + +Some merge conflicts are more complex, requiring you to manually modify lines to +resolve their conflicts. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface: + +1. Go to your merge request. +1. Select **Overview**, and scroll to the merge request reports section. +1. Find the merge conflicts message, and select **Resolve conflicts**. + GitLab shows a list of files with merge conflicts. +1. Select **Edit inline** to open the editor: +  +1. After you resolve the conflict, enter a **Commit message**. +1. Select **Commit to source branch**. + +## Resolve conflicts from the command line + +While most conflicts can be resolved through the GitLab user interface, some are too complex. +Complex conflicts are best fixed locally, from the command line, to give you the +most control over each change: + +1. Open the terminal and check out your feature branch. For example, `my-feature-branch`: + + ```shell + git checkout my-feature-branch + ``` + +1. [Rebase your branch](../../../topics/git/git_rebase.md#regular-rebase) against the + target branch (here, `main`) so Git prompts you with the conflicts: + + ```shell + git fetch + git rebase origin/main + ``` + +1. Open the conflicting file in your preferred code editor. +1. Find the conflict block: + - It begins with the marker: `<<<<<<< HEAD`. + - Next, it displays your changes. + - The marker `=======` indicates the end of your changes. + - Next, it displays the latest changes in the target branch. + - The marker `>>>>>>>` indicates the end of the conflict. +1. Edit the file: + 1. Choose which version (before or after `=======`) you want to keep. + 1. Delete the version you don't want to keep. + 1. Delete the conflict markers. +1. Save the file. +1. Repeat the process for each file that contains conflicts. +1. Stage your changes in Git: + + ```shell + git add . + ``` + +1. Commit your changes: + + ```shell + git commit -m "Fix merge conflicts" + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + + WARNING: + Up to this point, you can run `git rebase --abort` to stop the process. + Git aborts the rebase and rolls back the branch to the state you had before + running `git rebase`. + After you run `git rebase --continue`, you cannot abort the rebase. + +1. [Force-push](../../../topics/git/git_rebase.md#force-push) the changes to your + remote branch. + +## Merge commit strategy + +GitLab resolves conflicts by creating a merge commit in the source branch, but +does not merge it into the target branch. You can then review and test the +merge commit. Verify it contains no unintended changes and doesn't break your build. + +## Related topics + +- [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md). +- [Git GUI apps](https://git-scm.com/downloads/guis) to help you visualize the + differences between branches and resolve them. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 7edc379399b..078f8048900 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -38,6 +38,8 @@ Now, when you visit the merge request page, you can accept it If a fast-forward merge is not possible but a conflict free rebase is possible, a rebase button is offered. +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 diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index cee4df1f61e..006e6d4a8aa 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -172,11 +172,6 @@ is set for deletion, the merge request widget displays the > - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to -[disable the `retarget_merge_requests` flag](../../../administration/feature_flags.md). - In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is open. Merge requests are often chained in this manner, with one merge request diff --git a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png Binary files differnew file mode 100644 index 00000000000..f18ca640d38 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png Binary files differdeleted file mode 100644 index 52c715840f1..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differdeleted file mode 100644 index 625d47b1142..00000000000 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2c062c2c592..54b97eb5732 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -17,75 +17,50 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -To get started, read the [introduction to merge requests](getting_started.md). +Read more about [how to get started](getting_started.md). -## Merge request tabs +## View merge requests -Merge requests contain tabs at the top of the page to help you navigate to -important parts of the merge request: +You can view merge requests for your project, group, or yourself. - +### View merge requests for a project -- **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolve-a-thread) - and [code suggestions](reviews/suggestions.md). The right sidebar provides fields - to add assignees, reviewers, labels, and a milestone to your work, and the - [merge request widgets area](widgets.md) reports results from pipelines and tests. -- **Commits**: Contains a list of commits added to this merge request. For more - information, read [Commits tab in merge requests](commits.md). -- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/index.md) - pipelines and their status. -- **Changes**: Contains the diffs of files changed by this merge request. You can - [configure the display](changes.md). +To view all merge requests for a project: -## View merge requests +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. + +Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. + +### View merge requests for all projects in a group -To view a list of merge requests: +To view merge requests for all projects in a group: -- **Merge requests for a project**: Go to your project and select **Merge requests**, or use - the <kbd>g</kbd> + <kbd>m</kbd> [keyboard shortcut](../../shortcuts.md) from a page in your project. -- **All projects in a group**: Go to your group and select **Merge requests**. - If your group contains subgroups, this view also displays merge requests from the subgroup projects. - GitLab displays a count of open merge requests in the left sidebar, but - [caches the value](reviews/index.md#cached-merge-request-count) for groups with a large number of - open merge requests. -- **Merge requests assigned to you**: On any GitLab page, select **Merge requests** - in the top bar, or use the <kbd>Shift</kbd> + <kbd>m</kbd> - [global keyboard shortcut](../../shortcuts.md). +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Merge requests**. -GitLab displays open merge requests, with tabs to filter the list by open and closed status: +If your group contains subgroups, this view also displays merge requests from the subgroup projects. - +## View all merge requests assigned to you + +To view all merge requests assigned to you: + +1. On the top bar, put your cursor in the **Search** box. +1. From the dropdown list, select **Merge requests assigned to me**. + +Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. You can [search and filter](../../search/index.md#filter-issue-and-merge-request-lists), the results, or select a merge request to begin a review. -## Merge request sidebar - -The **Overview** tab of a merge request displays a sidebar. In this sidebar, you -can assign, categorize, and track progress on a merge request: - -- [**Assignee**](getting_started.md#assignee): Designate the directly responsible - individual (DRI) for a merge request. With - [multiple assignees](getting_started.md#multiple-assignees), you can assign a - merge request to more than one person at a time. -- [**Reviewer**](reviews/index.md): Designate a team member to review a merge request. - Higher tiers can assign multiple reviewers, and [require approvals](approvals/index.md) - from these reviewers. -- [**Milestone**](../milestones/index.md): Track time-sensitive changes. -- [**Time tracking**](../time_tracking.md): Time spent on a merge request. -- [**Labels**](../labels.md): Categorize a merge request and display it on - appropriate [issue boards](../issue_board.md). -- **Participants**: A list of users participating or watching a merge request. -- [**Notifications**](../../profile/notifications.md): A toggle to select whether - or not to receive notifications for updates to a merge request. - ## Add changes to a merge request If you have permission to add changes to a merge request, you can add your changes -to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment: +to an existing merge request in several ways, depending on the complexity of your +change and whether you need access to a development environment: -- [Edit changes in the Web IDE](../web_ide/index.md) in your browser. Use this +- [Edit changes in the Web IDE](../web_ide/index.md) in your browser with the + <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). Use this browser-based method to edit multiple files, or if you are not comfortable with Git commands. You cannot run tests from the Web IDE. - [Edit changes in Gitpod](../../../integration/gitpod.md#launch-gitpod-in-gitlab), if you @@ -158,3 +133,7 @@ For a web developer writing a webpage for your company's website: - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) - [GitLab keyboard shortcuts](../../shortcuts.md) +- [Comments and threads](../../discussions/index.md) +- [Suggest code changes](reviews/suggestions.md) +- [Commits](commits.md) +- [CI/CD pipelines](../../../ci/index.md) diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index d7c9c0f73ee..256dde4fa17 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -101,7 +101,7 @@ for details on avoiding two pipelines for a single merge request. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/index.md#skip-pipeline) prevent +When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent merge requests from being merged. To change this behavior: 1. Navigate to your project's **Settings > General** page. diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 4681ef09388..611f37a949b 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,85 +1,9 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: 'conflicts.md' +remove_date: '2022-01-26' --- -# Merge request conflict resolution **(FREE)** +This document was moved to [another location](conflicts.md). -Merge conflicts occur when two branches have different changes that cannot be -merged automatically. - -Git can merge changes between branches in most cases, but -occasionally Git requires your assistance to resolve the -conflicts manually. Typically, this is necessary when people change the same -parts of the same files. - -GitLab prevents merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases in GitLab -(see [conflicts available for resolution](#conflicts-available-for-resolution) -for information on when this is available). - - - -NOTE: -GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. The merge -commit can be reviewed and tested before the changes are merged. This prevents -unintended changes entering the target branch without review or breaking the -build. - -## Resolve conflicts: interactive mode - -Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections -highlighted: - - - -After all conflicts have been marked as using 'ours' or 'theirs', the conflict -can be resolved. Resolving conflicts merges the target branch of the merge -request into the source branch, using the options -chosen. If the source branch is `feature` and the target branch is `main`, -this is similar to performing `git checkout feature; git merge main` locally. - -## Resolve conflicts: inline editor - -Some merge conflicts are more complex, requiring you to manually modify a file to -resolve them. Use the merge conflict resolution editor to resolve complex -conflicts in the GitLab interface. Click **Edit inline** to open the editor. -After you're sure about your changes, click **Commit to source branch**. - - - -## Conflicts available for resolution - -GitLab allows resolving conflicts in a file where all of the below are true: - -- The file is text, not binary -- The file is in a UTF-8 compatible encoding -- The file does not already contain conflict markers -- The file, with conflict markers added, is not over 200 KB in size -- The file exists under the same path in both branches - -If any file in your merge request containing conflicts can't meet all of these -criteria, you can't resolve the merge conflict in the UI. - -Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this does not create a conflict: - -1. On branch `a`, doing `git mv file1 file2` -1. On branch `b`, doing `git mv file1 file3`. - -Instead, both files are present in the branch after the merge request is merged. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <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/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e6f84f1c357..597dcb3dfb9 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -17,6 +17,10 @@ your merge request, and makes [code suggestions](suggestions.md) you can accept from the user interface. When your work is reviewed, your team members can choose to accept or reject it. +You can review merge requests from the GitLab interface. If you install the +[GitLab Workflow VS Code extension](../../repository/vscode.md), you can also +review merge requests in Visual Studio Code. + ## Review a merge request > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. @@ -207,7 +211,7 @@ These features are associated with merge requests: When viewing the commit details page, GitLab links to the merge request(s) containing that commit. - [Merge requests versions](../versions.md): Select and compare the different versions of merge request diffs -- [Resolve conflicts](../resolve_conflicts.md): +- [Resolve conflicts](../conflicts.md): GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. - [Revert changes](../revert_changes.md): Revert changes from any commit from a merge request. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index ac1cd57fb99..7bfb8e52279 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -7,14 +7,13 @@ type: index, reference # Suggest changes **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. -> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request diff threads. Then, the merge request author (or other users with appropriate -[permission](../../../permissions.md)) is able to apply these suggestions with a click, -which generates a commit in the merge request authored by the user that suggested the changes. +[permission](../../../permissions.md)) can apply these suggestions with a click. +This action generates a commit in the merge request, authored by the user that suggested the changes. 1. Choose a line of code to be changed, add a new comment, then select the **Insert suggestion** icon in the toolbar: @@ -38,14 +37,15 @@ which generates a commit in the merge request authored by the user that suggeste  -After the author applies a suggestion, it's marked with the **Applied** label, -the thread is automatically resolved, and GitLab creates a new commit -and pushes the suggested change directly into the codebase in the merge request's -branch. The [Developer role](../../../permissions.md) is required to do so. +After the author applies a suggestion: -## Multi-line suggestions +1. The suggestion is marked as **Applied**. +1. The thread is resolved. +1. GitLab creates a new commit with the changes. +1. If the user has the [Developer role](../../../permissions.md), GitLab pushes + the suggested change directly into the codebase in the merge request's branch. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +## Multi-line suggestions Reviewers can also suggest changes to multiple lines with a single suggestion within merge request diff threads by adjusting the range offsets. The @@ -67,9 +67,9 @@ suggestion. ## Code block nested in suggestions -If you need to make a suggestion that involves a -[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks -instead of the usual three. +To add a suggestion that includes a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion +in four backticks instead of three:  @@ -95,14 +95,14 @@ You can also use following variables besides static text: | Variable | Description | Output example | |------------------------|-------------|----------------| -| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | -| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | -| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{branch_name}` | The name of the branch to which suggestions were applied. | `my-feature-branch` | +| `%{files_count}` | The number of files to which suggestions were applied.| **2** | +| `%{file_paths}` | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | | `%{project_name}` | The human-readable name of the project. | **My Project** | | `%{suggestions_count}` | The number of suggestions applied.| **3** | -| `%{username}` | The username of the user applying suggestion(s). | `user_1` | -| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | +| `%{username}` | The username of the user applying suggestions. | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestions. | **User 1** | For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to @@ -114,32 +114,32 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. -> - Custom commit messages for batch suggestions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) in GitLab 14.4. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. You can apply multiple suggestions at once to reduce the number of commits added to your branch to address your reviewers' requests. 1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: -  +  1. Add as many additional suggestions to the batch as you wish: -  +  1. To remove suggestions, select **Remove from batch**: -  +  1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You can optionally specify a custom commit message for [batch suggestions](#batch-suggestions) (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit message is used. -  +  WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. 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 27487003697..ee4320d5ea1 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 @@ -27,6 +27,17 @@ and steps below. - Access to your domain's server control panel to set up DNS records: - A DNS A or CNAME record pointing your domain to GitLab Pages server. - A DNS `TXT` record to verify your domain's ownership. +- Set either `external_http` or `external_https` in `/etc/gitlab/gitlab.rb` to the IP and port of + your [Pages Daemon](../../../../administration/pages/index.md#overview). + If you don't have IPv6, you can omit the IPv6 address. + + Example: + + ```ruby + # Redirect pages from HTTP to HTTPS + gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] # The secondary IPs for the GitLab Pages daemon + gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] # The secondary IPs for the GitLab Pages daemon + ``` ### Steps diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 4f2b62beab1..25382778b1d 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -13,31 +13,16 @@ the CI/CD pipeline to generate a Pages website. Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to. -Your GitLab repository should contain files specific to an SSG, or plain HTML. -After you complete these steps, you may need to do additional -configuration for the Pages site to generate properly. - -1. On the left sidebar, select **Project information**. -1. Click **Set up CI/CD**. - -  - - If this button is not available, CI/CD is already configured for - your project. You may want to browse the `.gitlab-ci.yml` files - [in these projects instead](https://gitlab.com/pages). - -1. From the **Apply a template** list, choose a template for the SSG you're using. - You can also choose plain HTML. - -  - - If you don't find a corresponding template, you can view the - [GitLab Pages group of sample projects](https://gitlab.com/pages). - These projects contain `.gitlab-ci.yml` files that you can modify for your needs. - You can also [learn how to write your own `.gitlab-ci.yml` - file for GitLab Pages](pages_from_scratch.md). - -1. Save and commit the `.gitlab-ci.yml` file. +Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete +these steps, you may have to do additional configuration for the Pages site to generate properly. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select the project's name. +1. From the **Add** (**{plus}**) dropdown, select **New file**. +1. From the **Select a template type** dropdown, select `.gitlab-ci.yml`. +1. From the **Apply a template** dropdown, in the **Pages** section, select the name of your SSG. +1. In the **Commit message** box, type the commit message. +1. Select **Commit changes**. If everything is configured correctly, the site can take approximately 30 minutes to deploy. diff --git a/doc/user/project/pages/img/choose_ci_template_v13_1.png b/doc/user/project/pages/img/choose_ci_template_v13_1.png Binary files differdeleted file mode 100644 index a0c25ba1642..00000000000 --- a/doc/user/project/pages/img/choose_ci_template_v13_1.png +++ /dev/null diff --git a/doc/user/project/pages/img/setup_ci_v13_1.png b/doc/user/project/pages/img/setup_ci_v13_1.png Binary files differdeleted file mode 100644 index 2cf1c05d6d8..00000000000 --- a/doc/user/project/pages/img/setup_ci_v13_1.png +++ /dev/null diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 45c2f1aaf04..59a2f0c2eba 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -223,16 +223,13 @@ Consider a Pages site deployed with the following files: ```plaintext public/ -├─┬ index.html -│ ├ data.html -│ └ info.html -│ +├── index.html +├── data.html +├── info.html ├── data/ │ └── index.html -├── info/ -│ └── details.html -└── other/ - └── index.html +└── info/ + └── details.html ``` Pages supports reaching each of these files through several different URLs. In @@ -241,23 +238,19 @@ specifies the directory. If the URL references a file that doesn't exist, but adding `.html` to the URL leads to a file that *does* exist, it's served instead. Here are some examples of what happens given the above Pages site: -| URL path | HTTP response | File served | -| -------------------- | ------------- | ----------- | -| `/` | `200 OK` | `public/index.html` | -| `/index.html` | `200 OK` | `public/index.html` | -| `/index` | `200 OK` | `public/index.html` | -| `/data` | `200 OK` | `public/data/index.html` | -| `/data/` | `200 OK` | `public/data/index.html` | -| `/data.html` | `200 OK` | `public/data.html` | -| `/info` | `200 OK` | `public/info.html` | -| `/info/` | `200 OK` | `public/info.html` | -| `/info.html` | `200 OK` | `public/info.html` | -| `/info/details` | `200 OK` | `public/info/details.html` | -| `/info/details.html` | `200 OK` | `public/info/details.html` | -| `/other` | `302 Found` | `public/other/index.html` | -| `/other/` | `200 OK` | `public/other/index.html` | -| `/other/index` | `200 OK` | `public/other/index.html` | -| `/other/index.html` | `200 OK` | `public/other/index.html` | +| URL path | HTTP response | +| -------------------- | ------------- | +| `/` | `200 OK`: `public/index.html` | +| `/index.html` | `200 OK`: `public/index.html` | +| `/index` | `200 OK`: `public/index.html` | +| `/data` | `302 Found`: redirecting to `/data/` | +| `/data/` | `200 OK`: `public/data/index.html` | +| `/data.html` | `200 OK`: `public/data.html` | +| `/info` | `302 Found`: redirecting to `/info/` | +| `/info/` | `404 Not Found` Error Page | +| `/info.html` | `200 OK`: `public/info.html` | +| `/info/details` | `200 OK`: `public/info/details.html` | +| `/info/details.html` | `200 OK`: `public/info/details.html` | Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 305bbb2ded0..15df69ee68c 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -69,8 +69,8 @@ time as pushing changes: | `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. Ex: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | If you use a push option that requires text with spaces in it, you need to enclose it in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: @@ -117,3 +117,13 @@ pipeline succeeds: ```shell git mwps origin <local-branch-name> ``` + +## Troubleshooting + +## Push options for merge request assignment ignored + +When you push a branch to GitLab, you can use push options to assign to (`merge_request.assign="<USERNAME>"`) +or unassign from (`merge_request.unassign="<USERNAME>"`) a user. If GitLab creates +the merge request successfully, but fails to assign or unassign the merge request +correctly, you can use the user ID instead. For more information, read the issue +[Push option `merge_request.(un)assign` seems to be ignored](https://gitlab.com/gitlab-org/gitlab/-/issues/325169). diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 45a83394c41..a4d7b94506b 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -78,6 +78,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | | `/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)) | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees 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. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 9e4d621dbc6..abedae5d10b 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -78,17 +78,172 @@ To create a new release through the GitLab UI: [release notes](#release-notes-description), or [assets links](#links). 1. Click **Create release**. -### Create release from GitLab CI +## Create a release by using a CI/CD job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. -You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/index.md#release) -by using a `release` node in the job definition. +You can create a release directly as part of the GitLab CI/CD pipeline +by using [the `release` keyword](../../../ci/yaml/index.md#release) in the job definition. The release is created only if the job processes without error. If the Rails API returns an error during release creation, the release job fails. -### Upcoming releases +### CI/CD example of the `release` keyword + +To create a release when you push a Git tag, or when you add a Git tag +in the UI by going to **Repository > Tags**: + +```yaml +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG # Run this job when a tag is created manually + script: + - echo 'running release_job' + release: + name: 'Release $CI_COMMIT_TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined + tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline. + ref: '$CI_COMMIT_TAG' + milestones: + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: # Optional, multiple asset links + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + +To create a release automatically when commits are pushed or merged to the default branch, +using a new Git tag that is defined with variables: + +```yaml +prepare_job: + stage: prepare # This stage must run before the release stage + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables + - echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file + artifacts: + reports: + dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs + +release_job: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + needs: + - job: prepare_job + artifacts: true + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo 'running release_job for $TAG' + release: + name: 'Release $TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG + tag_name: '$TAG' # variables must be defined elsewhere + ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the + milestones: # prepare_job + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + +NOTE: +Environment variables set in `before_script` or `script` are not available for expanding +in the same job. Read more about +[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). + +### Use a custom SSL CA certificate authority + +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, +which is used to verify the peer when the `release-cli` creates a release through the API using HTTPS with custom certificates. +The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the +[text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1) +or the `path/to/file` containing the certificate authority. +For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +release: + variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- + script: + - echo "Create release" + release: + name: 'My awesome release' + tag_name: '$CI_COMMIT_TAG' +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a +[custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), +either as a `file`, which requires the path to the certificate, or as a variable, +which requires the text representation of the certificate. + +### `release-cli` command line + +The entries under the `release` node are transformed into a `bash` command line and sent +to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). +You can also call the `release-cli` directly from a `script` entry. + +For example, if you use the YAML described previously: + +```shell +release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} +``` + +### Create multiple releases in a single pipeline + +A pipeline can have multiple `release` jobs, for example: + +```yaml +ios-release: + script: + - echo 'iOS release job' + release: + tag_name: v1.0.0-ios + description: 'iOS release v1.0.0' + +android-release: + script: + - echo 'Android release job' + release: + tag_name: v1.0.0-android + description: 'Android release v1.0.0' +``` + +### Release assets as Generic packages + +You can use [Generic packages](../../packages/generic_packages/index.md) to host your release assets. +For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/) +project. + +## Upcoming releases > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -238,14 +393,6 @@ The release title can be customized using the **Release title** field when creating or editing a release. If no title is provided, the release's tag name is used instead. -Guest users of private projects are allowed to view the **Releases** page -but are _not_ allowed to view details about the Git repository (in particular, -tag names). Because of this, release titles are replaced with a generic -title like "Release-1234" for Guest users to avoid leaking tag name information. - -See the [Release permissions](#release-permissions) section for -more information about permissions. - ### Tag name The release tag name should include the release version. GitLab uses [Semantic Versioning](https://semver.org/) @@ -569,11 +716,14 @@ In the API: ### View a release and download assets -- Users with [Reporter role or above](../../../user/permissions.md#project-members-permissions) +> [Changes were made to the Guest role access](https://gitlab.com/gitlab-org/gitlab/-/issues/335209) in GitLab 14.5. + +- Users with the [Reporter role or above](../../../user/permissions.md#project-members-permissions) + have read and download access to the project releases. +- Users with the [Guest role](../../../user/permissions.md#project-members-permissions) have read and download access to the project releases. -- Users with [Guest role](../../../user/permissions.md#project-members-permissions) - have read and download access to the project releases, however, - repository-related information are redacted (for example the Git tag name). + This includes associated Git-tag-names, release description, author information of the releases. + However, other repository-related information, such as [source code](#source-code), [release evidence](#release-evidence) are redacted. ### Create, update, and delete a release and its assets diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md new file mode 100644 index 00000000000..c23ceaa1aba --- /dev/null +++ b/doc/user/project/releases/release_cli.md @@ -0,0 +1,76 @@ +--- +type: reference, howto +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 +--- + +# Install the `release-cli` for the Shell executor + +> - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. +> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/jaime/release-cli/-/packages). + +When you use a runner with the Shell executor, you can download and install +the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html). +Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is available to use in your CI/CD jobs. + +## Install on Unix/Linux + +1. Download the binary for your system from S3, in the following example for amd64 systems: + + ```shell + curl --location --output /usr/local/bin/release-cli "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-linux-amd64" + ``` + + Or from the GitLab Package Registry: + + ```shell + curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-darwin-amd64" + ``` + +1. Give it permissions to execute: + + ```shell + sudo chmod +x /usr/local/bin/release-cli + ``` + +1. Verify `release-cli` is available: + + ```shell + $ release-cli -v + + release-cli version 0.6.0 + ``` + +## Install on Windows PowerShell + +1. Create a folder somewhere in your system, for example `C:\GitLab\Release-CLI\bin` + + ```shell + New-Item -Path 'C:\GitLab\Release-CLI\bin' -ItemType Directory + ``` + +1. Download the executable file: + + ```shell + PS C:\> Invoke-WebRequest -Uri "https://release-cli-downloads.s3.amazonaws.com/latest/release-cli-windows-amd64.exe" -OutFile "C:\GitLab\Release-CLI\bin\release-cli.exe" + + Directory: C:\GitLab\Release-CLI + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + d----- 3/16/2021 4:17 AM bin + ``` + +1. Add the directory to your `$env:PATH`: + + ```shell + $env:PATH += ";C:\GitLab\Release-CLI\bin" + ``` + +1. Verify `release-cli` is available: + + ```shell + PS C:\> release-cli -v + + release-cli version 0.6.0 + ``` diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 5cd025f017d..bc6bc799670 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -167,7 +167,7 @@ changed, GitLab records the name of the old default branch. If that branch is deleted, attempts to view a file or directory on it are redirected to the current default branch, instead of displaying the "not found" page. -## Resources +## Related topics - [Configure a default branch for your wiki](../../wiki/index.md) - [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 23d7aecc960..6aa32b1b816 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -39,7 +39,10 @@ For a commit to be verified by GitLab: - 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. + 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 + [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. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index de7459e6278..bb1a55f6b2b 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -41,7 +41,7 @@ to a branch in the repository. When you use the command line, you can commit mul If the project is configured with [GitLab CI/CD](../../../ci/index.md), you trigger a pipeline per push, not per commit. - **Skip pipelines:** - Add the [`ci skip`](../../../ci/yaml/index.md#skip-pipeline) keyword to + Add the [`ci skip`](../../../ci/pipelines/index.md#skip-a-pipeline) keyword to your commit message to make GitLab CI/CD skip the pipeline. - **Cross-link issues and merge requests:** Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages) @@ -82,14 +82,19 @@ prompted to open XCode. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. -All projects can be cloned into Visual Studio Code. To do that: +All projects can be cloned into Visual Studio Code from the GitLab user interface, but you +can also install the [GitLab Workflow VS Code extension](vscode.md) to clone from +Visual Studio Code: -1. From the GitLab UI, go to the project's overview page. -1. Click **Clone**. -1. Select **Clone with Visual Studio Code** under either HTTPS or SSH method. -1. Select a folder to clone the project into. +- From the GitLab interface: + 1. Go to the project's overview page. + 1. Select **Clone**. + 1. Under either the **HTTPS** or **SSH** method, select **Clone with Visual Studio Code**. + 1. Select a folder to clone the project into. -When VS Code has successfully cloned your project, it opens the folder. + After Visual Studio Code clones your project, it opens the folder. +- From Visual Studio Code, with the [extension](vscode.md) installed, use the + extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). ## Download the code in a repository @@ -243,6 +248,10 @@ When you [rename a user](../../profile/index.md#change-your-username), - The redirects are available as long as the original path is not claimed by another group, user, or project. +## Related links + +- [GitLab Workflow VS Code extension](vscode.md) + ## Troubleshooting ### Repository Languages: excessive CPU use diff --git a/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png Binary files differnew file mode 100644 index 00000000000..bc63322cd65 --- /dev/null +++ b/doc/user/project/repository/jupyter_notebooks/img/jupyter_notebook_diff_v14_5.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 2ad1504aac3..d040cc93876 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -4,22 +4,42 @@ group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- -# Jupyter Notebook Files **(FREE)** +# Jupyter Notebook files **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. +[Jupyter Notebook](https://jupyter.org/) (previously, IPython Notebook) files are used for +interactive computing in many fields. They contain a complete record of the +user's sessions and include: -[Jupyter](https://jupyter.org/) Notebook (previously IPython Notebook) files are used for -interactive computing in many fields and contain a complete record of the -user's sessions and include code, narrative text, equations, and rich output. +- Code. +- Narrative text. +- Equations. +- Rich output. -When added to a repository, Jupyter Notebooks with a `.ipynb` extension are -rendered to HTML when viewed: +When you add a Jupyter Notebook (with `.ipynb` extension) to your repository, +it's rendered into HTML when you view it:  Interactive features, including JavaScript plots, don't work when viewed in GitLab. +## Cleaner diffs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. +On GitLab.com, this feature is available. + +When commits include changes to Jupyter Notebook files, GitLab: + +- Transforms the machine-readable `.ipynb` file into a human-readable Markdown file. +- Displays a cleaner version of the diff that includes syntax highlighting. + +Code suggestions are not available on diffs and merge requests for `.ipynb` files. + + + ## Jupyter Git integration Jupyter can be configured as an OAuth application with repository access, acting diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index c4254655fcc..340d7b48a47 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -139,7 +139,7 @@ This sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update, and Git displays warnings about it. -## Mirror with Perforce Helix via Git Fusion **(PREMIUM)** +## Mirror with Perforce Helix with Git Fusion **(PREMIUM)** > Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png b/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png Binary files differdeleted file mode 100644 index e20dae09a4d..00000000000 --- a/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png +++ /dev/null diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 4532a80c2f5..361c0902ebf 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -7,102 +7,162 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** -Repository mirroring allows for the mirroring of repositories to and from external sources. You -can use it to mirror branches, tags, and commits between repositories. It helps you use -a repository outside of GitLab. +You can _mirror_ a repository to and from external sources. You can select which +repository serves as the source, and modify which parts of the repository are copied. +Branches, tags, and commits can be mirrored. -A repository mirror at GitLab updates automatically. You can also manually trigger an update: - -- At most once every five minutes on GitLab.com. -- According to a [limit set by the administrator](../../../../administration/instance_limits.md#pull-mirroring-interval) - on self-managed instances. - -There are two kinds of repository mirroring supported by GitLab: +Several mirroring methods exist: - [Push](push.md): for mirroring a GitLab repository to another location. - [Pull](pull.md): for mirroring a repository from another location to GitLab. +- [Bidirectional](bidirectional.md) mirroring is also available, but can cause conflicts. + +Mirror a repository when: + +- The canonical version of your project has migrated to GitLab. To keep providing a + copy of your project at its previous home, configure your GitLab repository as a + [push mirror](push.md). Changes you make to your GitLab repository are copied to + the old location. +- Your GitLab project is private, but some components can be shared publicly. + Configure your primary repository as a [push mirror](push.md) and push the portions + you want to make public. With this configuration, you can open-source specific + projects, contribute back to the open-source community, and protect the sensitive + parts of your project. +- You migrated to GitLab, but the canonical version of your project is somewhere else. + Configure your GitLab repository as a [pull mirror](pull.md) of the other project. + Your GitLab repository pulls copies of the commits, tags, and branches of project. + They become available to use on GitLab. + +## Create a repository mirror + +Prerequisite: + +- You must have at least the [Maintainer role](../../../permissions.md) for the project. +- If your mirror connects with `ssh://`, the host key must be detectable on the server, + or you must have a local copy of the key. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Enter a **Git repository URL**. For security reasons, the URL to the original + repository is only displayed to users with the [Maintainer role](../../../permissions.md) + or the [Owner role](../../../permissions.md) for the mirrored project. +1. Select a **Mirror direction**. +1. If you entered a `ssh://` URL, select either: + - **Detect host keys**: GitLab fetches the host keys from the server and displays the fingerprints. + - **Input host keys manually**, and enter the host key into **SSH host key**. + + When mirroring the repository, GitLab confirms at least one of the stored host keys + matches before connecting. This check can protect your mirror from malicious code injections, + or your password from being stolen. +1. Select an **Authentication method**. To learn more, read + [Authentication methods for mirrors](#authentication-methods-for-mirrors). +1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) + to ensure it is correct. +1. To prevent force-pushing over diverged refs, select [**Keep divergent refs**](push.md#keep-divergent-refs). +1. Optional. Select [**Mirror only protected branches**](#mirror-only-protected-branches). +1. Select **Mirror repository**. + +If you select `SSH public key` as your authentication method, GitLab generates a +public key for your GitLab repository. You must provide this key to the non-GitLab server. +To learn more, read [Get your SSH public key](#get-your-ssh-public-key). + +## Update a mirror When the mirror repository is updated, all new branches, tags, and commits are visible in the -project's activity feed. +project's activity feed. A repository mirror at GitLab updates automatically. +You can also manually trigger an update: -Users with the [Maintainer role](../../../permissions.md) for the project can also force an -immediate update, unless: +- At most once every five minutes on GitLab.com. +- According to [the pull mirroring interval limit](../../../../administration/instance_limits.md#pull-mirroring-interval) + set by the administrator on self-managed instances. -- The mirror is already being updated. -- The [limit for pull mirroring interval seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed after its last update. +### Force an update -For security reasons, the URL to the original repository is only displayed to users with the -[Maintainer role](../../../permissions.md) or the [Owner role](../../../permissions.md) for the mirrored -project. +While mirrors are scheduled to update automatically, you can force an immediate update unless: -## Use cases +- The mirror is already being updated. +- The [interval, in seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) + for pull mirroring limits has not elapsed after its last update. -The following are some possible use cases for repository mirroring: +Prerequisite: -- You migrated to GitLab but still must keep your project in another source. In that case, you - can set it up to mirror to GitLab (pull) and all the essential history of commits, tags, - and branches are available in your GitLab instance. **(PREMIUM)** -- You have old projects in another source that you don't use actively anymore, but don't want to - remove for archiving purposes. In that case, you can create a push mirror so that your active - GitLab repository can push its changes to the old location. -- You are a GitLab self-managed user for privacy reasons and your instance is closed to the public, - but you still have certain software components that you want open sourced. In this case, utilizing - GitLab to be your primary repository which is closed from the public, and using push mirroring to a - GitLab.com repository that's public, allows you to open source specific projects and contribute back - to the open source community. +- You must have at least the [Maintainer role](../../../permissions.md) for the project. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Scroll to **Mirrored repositories** and identify the mirror to update. +1. Select **Update now** (**{retry}**): +  ## Mirror only protected branches **(PREMIUM)** > Moved to GitLab Premium in 13.9. -Based on the mirror direction that you choose, you can opt to mirror only the +You can choose to mirror only the [protected branches](../../protected_branches.md) in the mirroring project, -either from or to your remote repository. For pull mirroring, non-protected branches in -the mirroring project are not mirrored and can diverge. +either from or to your remote repository. For [pull mirroring](pull.md), +non-protected branches in the mirroring project are not mirrored and can diverge. + +To use this option, select **Only mirror protected branches** when you create a repository mirror. -To use this option, check the **Only mirror protected branches** box when -creating a repository mirror. **(PREMIUM)** +## Authentication methods for mirrors -## SSH authentication +When you create a mirror, you must configure the authentication method for it. +GitLab supports these authentication methods: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. +- [SSH authentication](#ssh-authentication). +- Password. + +### SSH authentication SSH authentication is mutual: -- You have to prove to the server that you're allowed to access the repository. -- The server also has to prove to *you* that it's who it claims to be. +- You must prove to the server that you're allowed to access the repository. +- The server must also *prove to you* that it's who it claims to be. -You provide your credentials as a password or public key. The server that the -other repository resides on provides its credentials as a "host key", the -fingerprint of which needs to be verified manually. +For SSH authentication, you provide your credentials as a password or _public key_. +The server that the other repository resides on provides its credentials as a _host key_. +You must [verify the fingerprint](#verify-a-host-key) of this host key manually. If you're mirroring over SSH (using an `ssh://` URL), you can authenticate using: - Password-based authentication, just as over HTTPS. -- Public key authentication. This is often more secure than password authentication, +- Public key authentication. This method is often more secure than password authentication, especially when the other repository supports [deploy keys](../../deploy_keys/index.md). -To get started: - -1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. Enter an `ssh://` URL for mirroring. +### Get your SSH public key -NOTE: -SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. +When you mirror a repository and select the **SSH public key** as your +authentication method, GitLab generates a public key for you. The non-GitLab server +needs this key to establish trust with your GitLab repository. To copy your SSH public key: -Entering the URL adds two buttons to the page: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Scroll to **Mirrored repositories**. +1. Identify the correct repository, and select **Copy SSH public key** (**{copy-to-clipboard}**). +1. Add the public SSH key to the other repository's configuration: + - If the other repository is hosted on GitLab, add the public SSH key + as a [deploy key](../../../project/deploy_keys/index.md). + - If the other repository is hosted elsewhere, add the key to + your user's `authorized_keys` file. Paste the entire public SSH key into the + file on its own line and save it. -- **Detect host keys**. -- **Input host keys manually**. +If you must change the key at any time, you can remove and re-add the mirror +to generate a new key. Update the other repository with the new +key to keep the mirror running. -If you select the: +NOTE: +The generated keys are stored in the GitLab database, not in the file system. Therefore, +SSH public key authentication for mirrors cannot be used in a pre-receive hook. -- **Detect host keys** button, GitLab fetches the host keys from the server and display the fingerprints. -- **Input host keys manually** button, a field is displayed where you can paste in host keys. +### Verify a host key -Assuming you used the former, you now must verify that the fingerprints are -those you expect. GitLab.com and other code hosting sites publish their -fingerprints in the open for you to check: +When using a host key, always verify the fingerprints match what you expect. +GitLab.com and other code hosting sites publish their fingerprints +for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) @@ -112,9 +172,11 @@ fingerprints in the open for you to check: - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) - [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) -Other providers vary. If you're running self-managed GitLab, or otherwise -have access to the server for the other repository, you can securely gather the -key fingerprints: +Other providers vary. You can securely gather key fingerprints with the following +command if you: + +- Run self-managed GitLab. +- Have access to the server for the other repository. ```shell $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - @@ -123,45 +185,9 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - 2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) ``` -NOTE: -You must exclude `-E md5` for some older versions of SSH. - -When mirroring the repository, GitLab checks that at least one of the -stored host keys matches before connecting. This can prevent malicious code from -being injected into your mirror, or your password being stolen. - -### SSH public key authentication - -To use SSH public key authentication, you must also choose that option -from the **Authentication method** dropdown. When the mirror is created, -GitLab generates a 4096-bit RSA key that can be copied by selecting the **Copy SSH public key** button. - - +Older versions of SSH may require you to remove `-E md5` from the command. -You then must add the public SSH key to the other repository's configuration: - -- If the other repository is hosted on GitLab, you should add the public SSH key - as a [deploy key](../../../project/deploy_keys/index.md). -- If the other repository is hosted elsewhere, you must add the key to - your user's `authorized_keys` file. Paste the entire public SSH key into the - file on its own line and save it. - -If you must change the key at any time, you can remove and re-add the mirror -to generate a new key. Update the other repository with the new -key to keep the mirror running. - -NOTE: -The generated keys are stored in the GitLab database, not in the file system. Therefore, -SSH public key authentication for mirrors cannot be used in a pre-receive hook. - -## Force an update **(FREE)** - -While mirrors are scheduled to update automatically, you can always force an update by using the -update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. - - - -## Resources +## Related topics - Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) - [Disable mirrors for a project](../../../admin_area/settings/visibility_and_access_controls.md#enable-project-mirroring) @@ -171,24 +197,33 @@ update button which is available on the **Mirroring repositories** section of th Should an error occur during a push, GitLab displays an **Error** highlight for that repository. Details on the error can then be seen by hovering over the highlight text. -### 13:Received RST_STREAM with error code 2 with GitHub +### Received RST_STREAM with error code 2 with GitHub + +If you receive this message while mirroring to a GitHub repository: + +```plaintext +13:Received RST_STREAM with error code 2 +``` + +Your GitHub settings might be set to block pushes that expose your email address +used in commits. To fix this problem, either: -If you receive a "13:Received RST_STREAM with error code 2" message while mirroring to a GitHub repository, -your GitHub settings might be set to block pushes that expose your email address used in commits. Either -set your email address on GitHub to be public, or disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. +- Set your GitHub email address to public. +- Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. -### 4:Deadline Exceeded +### Deadline Exceeded -When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you +When upgrading to GitLab 11.11.8 or later, a change in how usernames are represented means that you must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. ### Connection blocked because server only allows public key authentication -As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a -[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, -you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. +The connection between GitLab and the remote repository is blocked. Even if a +[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) +is successful, you must check any networking components in the route from GitLab +to the remote server for blockage. -For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. +This error can occur when a firewall performs a `Deep SSH Inspection` on outgoing packets. ### Could not read username: terminal prompts disabled @@ -196,29 +231,31 @@ If you receive this error after creating a new project using [GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/): ```plaintext -"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled\n": exit status 128." +"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': +terminal prompts disabled\n": exit status 128." ``` Check if the repository owner is specified in the URL of your mirrored repository: -1. Go to your project. +1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. -1. Select **Mirroring repositories**. -1. If no repository owner is specified, delete and add the URL again in this format: +1. Expand **Mirroring repositories**. +1. If no repository owner is specified, delete and add the URL again in this format, + replacing `OWNER`, `ACCOUNTNAME`, and `REPONAME` with your values: ```plaintext - https://**<repo_owner>**@bitbucket.org/<accountname>/<reponame>.git + https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git ``` -The repository owner is needed for Bitbucket to connect to the repository for mirroring. +When connecting to the repository for mirroring, Bitbucket requires the repository owner in the string. ### Pull mirror is missing LFS files In some cases, pull mirroring does not transfer LFS files. This issue occurs when: - You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. - There is [an issue to fix this for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). + An issue exists [to fix this problem for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). - You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. - This was [fixed in GitLab 14.0.6](https://gitlab.com/gitlab-org/gitlab/-/issues/335123). + [Fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/335123) in GitLab 14.0.6. - You mirror an external repository using object storage. - There is [an issue to fix this](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). + An issue exists [to fix this problem](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index d1943cbfd71..4c437d0f8c8 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -41,7 +41,7 @@ After you configure a GitLab repository as a pull mirror: 1. Sidekiq becomes available to process updates, mirrors are updated. If the update process: - **Succeeds**: An update is enqueued again with at least a 30 minute wait. - **Fails**: The update is attempted again later. After 14 failures, a mirror is marked as a - [hard failure](#hard-failure) and is no longer enqueued for updates. A branch diverging + [hard failure](#fix-hard-failures-when-mirroring) and is no longer enqueued for updates. A branch diverging from its upstream counterpart can cause failures. To prevent branches from diverging, configure [Overwrite diverged branches](#overwrite-diverged-branches) when you create your mirror. @@ -102,7 +102,7 @@ updates are pulled immediately. For more information, read [Start the pull mirroring process for a project](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). -## Hard failure +## Fix hard failures when mirroring > Moved to GitLab Premium in 13.9. @@ -112,7 +112,7 @@ and mirroring attempts stop. This failure is visible in either the: - Project's main dashboard. - Pull mirror settings page. -You can resume the project mirroring again by [forcing an update](index.md#force-an-update). +To resume project mirroring, [force an update](index.md#force-an-update). ## Related topics diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md new file mode 100644 index 00000000000..bbf14a71653 --- /dev/null +++ b/doc/user/project/repository/vscode.md @@ -0,0 +1,47 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab Workflow extension for VS Code **(FREE)** + +The [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +integrates GitLab with Visual Studio Code. You can decrease context switching and +do more day-to-day tasks in Visual Studio Code, such as: + +- [View issues](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-issues-review-mrs). +- Run [common commands](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#commands) + from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). +- Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) + merge requests directly from Visual Studio Code. +- [Validate your GitLab CI configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration). +- [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). +- [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) + and paste snippets to, and from, your editor. +- [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) + without cloning them. + +## Download the extension + +Download the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). + +## Configure the extension + +After you [download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#extension-settings): + +- [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). +- [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. + +## Report issues with the extension + +Report any issues, bugs, or feature requests in the +[`gitlab-vscode-extension` issue queue](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues). + +## Related topics + +- [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) +- [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) +- The extension source code is available in the + [`gitlab-vscode-extension`](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) project. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 17031dd29af..2db7ae308bd 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -158,7 +158,7 @@ can start signing your tags: git config --global tag.gpgsign true ``` -## Resources +## Related topics - [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 661bd3e0598..6ee23c91680 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -38,7 +38,9 @@ see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) A paginated list of requirements is available in each project, and there you can create a new requirement. -Users with Reporter or higher [permissions](../../permissions.md) can create requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To create a requirement: @@ -66,7 +68,9 @@ next to the requirement title. You can edit a requirement from the requirements list page. -Users with Reporter or higher [permissions](../../permissions.md) can edit requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To edit a requirement: @@ -80,7 +84,9 @@ To edit a requirement: You can archive an open requirement while you're in the **Open** tab. -Users with Reporter or higher [permissions](../../permissions.md) can archive requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To archive a requirement, select **Archive** (**{archive}**). @@ -90,7 +96,9 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. -Users with Reporter or higher [permissions](../../permissions.md) can reopen archived requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md).  @@ -209,13 +217,13 @@ requirements_confirmation: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. +You must have at least the Reporter [role](../../permissions.md). + You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) with the columns `title` and `description`. After the import, the user uploading the CSV file is set as the author of the imported requirements. -Users with Reporter or higher [permissions](../../permissions.md) can import requirements. - ### Import the file Before you import your file: @@ -281,7 +289,9 @@ By exporting requirements, you and your team can import them into another tool o your customers. Exporting requirements can aid collaboration with higher-level systems, as well as audit and regulatory compliance tasks. -Users with Reporter or higher [permissions](../../permissions.md) can export requirements. +Prerequisite: + +- You must have at least the Reporter [role](../../permissions.md). To export requirements: diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index fa5ef35418a..4f8e068ca2d 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -86,10 +86,10 @@ To improve your project's security, we recommend the following: - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. Unblocked email spam can result in many spam issues being created. -The unique internal email address is visible to project members with Maintainer (or higher) -[permission level](../permissions.md) -in your GitLab instance. However, when using an email alias externally, an end user -(issue creator) cannot see the internal email address displayed in the information note. +The unique internal email address is visible to project members at least +the Reporter [role](../permissions.md) in your GitLab instance. +An external user (issue creator) cannot see the internal email address +displayed in the information note. ### Using customized email templates @@ -137,15 +137,23 @@ You can use these placeholders to be automatically replaced in each email: #### New Service Desk issues -You can select one [issue description template](description_templates.md#create-an-issue-template) +You can select one [description template](description_templates.md#create-an-issue-template) **per project** to be appended to every new Service Desk issue's description. -Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. -To use a custom issue template with Service Desk, in your project: +You can set description templates at various levels: -1. [Create a description template](description_templates.md#create-an-issue-template) -1. Go to **Settings > General > Service Desk**. -1. From the dropdown **Template to append to all Service Desk issues**, select your template. +- The entire [instance](description_templates.md#set-instance-level-description-templates). +- A specific [group or subgroup](description_templates.md#set-group-level-description-templates). +- A specific [project](description_templates.md#set-a-default-template-for-merge-requests-and-issues). + +The templates are inherited. For example, in a project, you can also access templates set for the instance or the project’s parent groups. + +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. ### Using a custom email display name @@ -156,7 +164,8 @@ this name in the `From` header. The default display name is `GitLab Support Bot` To edit the custom email display name: -1. In a project, go to **Settings > General > Service Desk**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General > Service Desk**. 1. Enter a new name in **Email display name**. 1. Select **Save Changes**. @@ -166,13 +175,13 @@ To edit the custom email display name: > - [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 -both a [custom mailbox](#configuring-a-custom-mailbox) and a +a [custom mailbox](#configuring-a-custom-mailbox). If you want you can also configure a [custom suffix](#configuring-a-custom-email-address-suffix). #### Configuring a custom mailbox NOTE: -On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, so you only have to configure the +On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, you can still configure the [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. Using the `service_desk_email` configuration, you can customize the mailbox @@ -198,7 +207,7 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip service_desk_email: enabled: true address: "project_contact+%{key}@example.com" - user: "project_support@example.com" + user: "project_contact@example.com" password: "[REDACTED]" host: "imap.gmail.com" port: 993 @@ -215,7 +224,7 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip ```ruby gitlab_rails['service_desk_email_enabled'] = true gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" - gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" + gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" gitlab_rails['service_desk_email_password'] = "[REDACTED]" gitlab_rails['service_desk_email_mailbox_name'] = "inbox" gitlab_rails['service_desk_email_idle_timeout'] = 60 @@ -271,6 +280,8 @@ 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. + ## Using Service Desk You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). diff --git a/doc/user/project/settings/img/general_settings_v13_11.png b/doc/user/project/settings/img/general_settings_v13_11.png Binary files differdeleted file mode 100644 index 9da5acdf82e..00000000000 --- a/doc/user/project/settings/img/general_settings_v13_11.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_download_export.png b/doc/user/project/settings/img/import_export_download_export.png Binary files differindex c7ab7565fc7..62292e99e8e 100644 --- a/doc/user/project/settings/img/import_export_download_export.png +++ b/doc/user/project/settings/img/import_export_download_export.png diff --git a/doc/user/project/settings/img/import_export_export_button.png b/doc/user/project/settings/img/import_export_export_button.png Binary files differindex 6933e3edfcc..6f3663d64e8 100644 --- a/doc/user/project/settings/img/import_export_export_button.png +++ b/doc/user/project/settings/img/import_export_export_button.png diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6c3bf731cf8..74879dae2d6 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -2,7 +2,6 @@ stage: Manage group: Import info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, howto --- # Project import/export **(FREE)** @@ -159,7 +158,9 @@ To export a project and its data, follow these steps: 1. Go to your project's homepage. -1. Click **Settings** in the sidebar. +1. Select **Settings** in the sidebar. + +1. Scroll down and expand the **Advanced** section. 1. Scroll down to find the **Export project** button: @@ -178,12 +179,14 @@ To export a project and its data, follow these steps: ## Import the project +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. + WARNING: Only import projects from sources you trust. If you import a project from an untrusted source, it may be possible for an attacker to steal your sensitive data. 1. The GitLab project import feature is the first import option when creating a - new project. Click on **GitLab export**: + new project. Select **GitLab export**:  @@ -191,7 +194,7 @@ may be possible for an attacker to steal your sensitive data.  -1. Click on **Import project** to begin importing. Your newly imported project +1. Select **Import project** to begin importing. Your newly imported project page appears shortly. NOTE: @@ -199,9 +202,8 @@ If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. -NOTE: -The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. +The maximum import file size can be set by the Administrator, and the default is `0` (unlimited). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). ### Project import status @@ -224,6 +226,11 @@ To help avoid abuse, by default, users are rate limited to: GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](../import/index.md#automate-group-and-project-import). + ## Troubleshooting ### Project fails to import due to mismatch @@ -233,15 +240,18 @@ does not match between the exported project, and the project import, the project Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and either: - Ensure shared runners are enabled in both the source and destination projects. -- Disable shared runners on the parent group when you import the project. +- Disable shared runners on the parent group when you import the project. -### Import workaround for large repositories +### Import workarounds for large repositories [Maximum import size limitations](#import-the-project) -can prevent an import from being successful. -If changing the import limits is not possible, -the following local workflow can be used to temporarily -reduce the repository size for another import attempt. +can prevent an import from being successful. If changing the import limits is not possible, you can +try one of the workarounds listed here. + +#### Workaround option 1 + +The following local workflow can be used to temporarily +reduce the repository size for another import attempt: 1. Create a temporary working directory from the export: @@ -291,6 +301,58 @@ reduce the repository size for another import attempt. delete the temporary, `smaller-tmp-main` branch, and the local, temporary data. +#### Workaround option 2 + +Rather than attempting to push all changes at once, this workaround: + +- Separates the project import from the Git Repository import +- Incrementally pushes the repository to GitLab + +1. Make a local clone of the repository to migrate. In a later step, you push this clone outside of + the project export. +1. Download the export and remove the `project.bundle` (which contains the Git repository): + + ```shell + tar -czvf new_export.tar.gz --exclude='project.bundle' @old_export.tar.gz + ``` + +1. Import the export without a Git repository. It asks you to confirm to import without a + repository. +1. Save this bash script as a file and run it after adding the appropriate origin. + + ```shell + #!/bin/sh + + # ASSUMPTIONS: + # - The GitLab location is "origin" + # - The default branch is "main" + # - This will attempt to push in chunks of 500MB (dividing the total size by 500MB). + # Decrease this size to push in smaller chunks if you still receive timeouts. + + git gc + SIZE=$(git count-objects -v 2> /dev/null | grep size-pack | awk '{print $2}') + + # Be conservative... and try to push 2GB at a time + # (given this assumes each commit is the same size - which is wrong) + BATCHES=$(($SIZE / 500000)) + TOTAL_COMMITS=$(git rev-list --count HEAD) + if (( BATCHES > TOTAL_COMMITS )); then + BATCHES=$TOTAL_COMMITS + fi + + INCREMENTS=$(( ($TOTAL_COMMITS / $BATCHES) - 1 )) + + for (( BATCH=BATCHES; BATCH>=1; BATCH-- )) + do + COMMIT_NUM=$(( $BATCH - $INCREMENTS )) + COMMIT_SHA=$(git log -n $COMMIT_NUM --format=format:%H | tail -1) + 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 + ``` + ### Manually execute export steps Exports sometimes fail without giving enough information to troubleshoot. In these cases, it can be diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 30def6ae80f..5c4d4649240 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -28,12 +28,32 @@ functionality of a project. Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics: - - The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +#### Topics + +Use topics to categorize projects and find similar new projects. + +To assign topics to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings** > **General**. +1. Under **Topics**, enter the project topics. Existing popular topics are suggested as you type. +1. Select **Save changes**. + +For GitLab.com, explore popular topics on the [Explore topics page](../working_with_projects.md#explore-topics). +When you select a topic, you can see relevant projects. + +NOTE: +The assigned topics are visible only to everyone with access to the project, +but everyone can see which topics exist at all on the GitLab instance. +Do not include sensitive information in the name of a topic. + +If you're an instance administrator, see also +[Administering topics](../../admin_area/index.md#administering-topics). + #### Compliance frameworks **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. @@ -157,7 +177,9 @@ audit trail: include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch. + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch + rules: + - exists: '$CI_CONFIG_PATH' ``` ##### Ensure compliance jobs are always run @@ -236,7 +258,7 @@ Use the switches to enable or disable the following features: | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/). | -| **Operations** | ✓ | Control access to [operations dashboard](../../../operations/index.md). | +| **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | Some features depend on others: @@ -293,6 +315,7 @@ Set up your project's merge request settings: - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). +- Configure [merge commit message template](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cae9276eafd..85e412e7a41 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -10,6 +10,7 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) except they are attached to a project rather than a user. They can be used to: @@ -32,6 +33,9 @@ Project access tokens: For examples of how you can use a project access token to authenticate with the API, see the [relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). +NOTE: +For GitLab.com and self-managed instances, the default prefix is `glpat-`. + ## Creating a project access token 1. Log in to GitLab. @@ -58,7 +62,9 @@ For the bot: - The name is set to the name of the token. - The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. +- The email is set to `project{project_id}_bot@example.com`, for example `project123_bot@example.com`. +- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`, for example `project_123_bot1`. +- For additional acess tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`, for example `project123_bot1@example.com` API calls made with a project access token are associated with the corresponding bot user. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 71cf0c03549..d75a180492e 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -15,7 +15,8 @@ projects by providing an advanced editor with commit staging. ## Open the Web IDE -You can open the Web IDE when viewing a file, from the repository file list, +Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md) to open the Web IDE. +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* - @@ -100,12 +101,13 @@ same core features for highlighting and linking to particular lines in the edite ## Schema based validation -> - Support for validation based on predefined schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. -> - It was deployed behind a feature flag, disabled by default. -> - It's enabled on GitLab.com. -> - It cannot be enabled or disabled per-project. -> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-validation-based-on-predefined-schemas). -> - Support for validation based on custom schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `schema_linting`. +This feature cannot be enabled or disabled per-project. +On GitLab.com, this feature is available. +You should not use this feature for production environments. The Web IDE provides validation support for certain JSON and YAML files using schemas based on the [JSON Schema Store](https://www.schemastore.org/json/). @@ -115,28 +117,9 @@ based on the [JSON Schema Store](https://www.schemastore.org/json/). The Web IDE has validation for certain files built in. This feature is only supported for the `*.gitlab-ci.yml` files. -#### Enable or disable validation based on predefined schemas **(FREE SELF)** - -Validation based on predefined schemas is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default** for self-managed instances, -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:schema_linting) -``` - -To disable it: - -```ruby -Feature.disable(:schema_linting) -``` - ### Custom schemas **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in GitLab 13.4. The Web IDE also allows you to define custom schemas for certain JSON/YAML files in your project. You can do so by defining a `schemas` entry in the `.gitlab/.gitlab-webide.yml` file inside the diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md new file mode 100644 index 00000000000..731fed2595a --- /dev/null +++ b/doc/user/project/wiki/group.md @@ -0,0 +1,71 @@ +--- +stage: Create +group: Editor +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, how-to +--- + +# Group wikis **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 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), +to ensure all group members have the correct access permissions to contribute. +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. + 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). + +Similar to project wikis, group members with the [Developer role](../../permissions.md#group-members-permissions) +and higher can edit group wikis. Group wiki repositories can be moved using the +[Group repository storage moves API](../../../api/group_repository_storage_moves.md). + +## View a group wiki + +To access a group wiki: + +1. On the top bar, select **Menu > Groups** and find your group. +1. To display the wiki, either: + - On the left sidebar, select **Wiki**. + - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + [wiki keyboard shortcut](../../shortcuts.md). + +## Export a group wiki + +> Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247). + +Users with the [Owner role](../../permissions.md) in a group can +[import and export group wikis](../../group/settings/import_export.md) when importing +or exporting a group. + +Content created in a group wiki is not deleted when an account is downgraded or a +GitLab trial ends. The group wiki data is exported whenever the group owner of +the wiki is exported. + +To access the group wiki data from the export file if the feature is no longer +available, you have to: + +1. Extract the [export file tarball](../../group/settings/import_export.md) with + this command, replacing `FILENAME` with your file's name: + `tar -xvzf FILENAME.tar.gz` +1. Browse to the `repositories` directory. This directory contains a + [Git bundle](https://git-scm.com/docs/git-bundle) with the extension `.wiki.bundle`. +1. Clone the Git bundle into a new repository, replacing `FILENAME` with + your bundle's name: `git clone FILENAME.wiki.bundle` + +All files in the wiki are available in this Git repository. + +## Related topics + +- [Wiki settings for administrators](../../../administration/wikis/index.md) +- [Project wikis API](../../../api/wikis.md) +- [Group repository storage moves API](../../../api/group_repository_storage_moves.md) +- [Group wikis API](../../../api/group_wikis.md) +- [Wiki keyboard shortcuts](../../shortcuts.md#wiki-pages) +- [Epic: Feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e2a8167b14c..5d2a0530f68 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -12,16 +12,6 @@ to keep it in the same project as your code, you can use the wiki GitLab provide in each GitLab project. Every wiki is a separate Git repository, so you can create wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). -To access the wiki for a project or group, go to the page for your project or group -and either: - -- In the left sidebar, select **Wiki**. -- On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> - [wiki keyboard shortcut](../../shortcuts.md). - -If **Wiki** is not listed in the left sidebar of your project, a project administrator -has [disabled it](#enable-or-disable-a-project-wiki). - GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. Wiki pages written in Markdown support all [Markdown features](../../markdown.md), and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) @@ -35,6 +25,19 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se  +## View a project wiki + +To access a project wiki: + +1. On the top bar, select **Menu > Projects** and find your project. +1. To display the wiki, either: + - On the left sidebar, select **Wiki**. + - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + [wiki keyboard shortcut](../../shortcuts.md). + +If **Wiki** is not listed in the left sidebar of your project, a project administrator +has [disabled it](#enable-or-disable-a-project-wiki). + ## Configure a default branch for your wiki > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221159) in GitLab 14.1. @@ -56,7 +59,10 @@ When a wiki is created, it is empty. On your first visit, you can create the home page users see when viewing the wiki. This page requires a specific title to be used as your wiki's home page. To create it: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Select **Create your first page**. 1. GitLab requires this first page be titled `home`. The page with this title serves as the front page for your wiki. @@ -71,7 +77,10 @@ to be used as your wiki's home page. To create it: Users with the [Developer role](../../permissions.md) can create new wiki pages: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. 1. Add a title for your new page. Page titles use @@ -135,7 +144,10 @@ may not be able to check out the wiki locally afterward. You need at least the [Developer role](../../permissions.md) to edit a wiki page: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the page you want to edit, and either: - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). - Select the edit icon (**{pencil}**). @@ -151,7 +163,10 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). You need at least the [Developer role](../../permissions.md) to delete a wiki page: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the page you want to delete. 1. Select the edit icon (**{pencil}**). 1. Select **Delete page**. @@ -161,7 +176,10 @@ You need at least the [Developer role](../../permissions.md) to delete a wiki pa You need at least the [Developer role](../../permissions.md) to move a wiki page: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. For example, if you have a wiki page @@ -172,9 +190,7 @@ You need at least the [Developer role](../../permissions.md) to move a wiki page ## View history of a wiki page The changes of a wiki page over time are recorded in the wiki's Git repository. -To view the changes for a wiki page, select **Page history**. - -From the history page you can see: +The history page shows:  @@ -184,13 +200,25 @@ From the history page you can see: - The last update. - Previous revisions, by selecting a revision number in the **Page version** column. +To view the changes for a wiki page: + +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. +1. Go to the page you want to view history for. +1. Select **Page history**. + ### View changes between page versions > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in. @@ -203,10 +231,12 @@ You can see the changes made in a version of a wiki page, similar to versioned d > - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** -GitLab tracks wiki creation, deletion, and update events. These events are displayed on the -[user profile](../../profile/index.md#access-your-user-profile), -[group](../../group/index.md#view-group-activity), -and [project](../working_with_projects.md#project-activity) activity pages. +GitLab tracks wiki creation, deletion, and update events. These events are displayed on these pages: + +- [User profile](../../profile/index.md#access-your-user-profile). +- Activity pages, depending on the type of wiki: + - [Group activity](../../group/index.md#view-group-activity). + - [Project activity](../working_with_projects.md#project-activity). Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). @@ -218,7 +248,10 @@ You need at least the [Developer role](../../permissions.md) to customize the wi navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. Go to your project or group and select **Wiki**. +1. On the top bar, select **Menu**. + - For project wikis, select **Projects** and find your project. + - For group wikis, select **Groups** and find your group. +1. On the left sidebar, select **Wiki**. 1. In the top right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -241,42 +274,20 @@ Support for displaying a generated table of contents with a custom side navigati ## Enable or disable a project wiki Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) -can enable or disable the project wiki by following the instructions in +can enable or disable a project wiki by following the instructions in [Sharing and permissions](../settings/index.md#sharing-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). -## Group wikis **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. - -Group wikis work the same way as project wikis. Their usage is similar to project -wikis, with a few limitations: - -- Git LFS is not supported. -- Group wikis are not included in global search. -- Changes to group wikis don't show up in the group's activity feed. - -For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). - -Group wikis can be edited by members with the [Developer role](../../permissions.md#group-members-permissions) -and above. Group wiki repositories can be moved using the -[Group repository storage moves API](../../../api/group_repository_storage_moves.md). - -### Export a group wiki **(PREMIUM)** - -Users with the [Owner role](../../permissions.md) in a group can -[import and export group wikis](../../group/settings/import_export.md) when importing -or exporting a group. - -Content created in a group wiki is not deleted when an account is downgraded or a GitLab trial ends. +You can't disable [group wikis](group.md) from the GitLab user interface. ## Link an external wiki To add a link to an external wiki from a project's left sidebar: -1. Go to your project and select **Settings > Integrations**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. 1. (Optional) Select **Test settings** to verify the connection. @@ -291,7 +302,8 @@ To hide the internal wiki from the sidebar, [disable the project's wiki](#disabl To hide the link to an external wiki: -1. Go to your project and select **Settings > Integrations**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **External wiki**. 1. In the **Enable integration** section, clear the **Active** checkbox. 1. Select **Save changes**. @@ -300,6 +312,7 @@ To hide the link to an external wiki: To disable a project's internal wiki: +1. On the top bar, select **Menu > Projects** and find your project. 1. Go to your project and select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). @@ -356,7 +369,7 @@ For the status of the ongoing development for CommonMark and GitLab Flavored Mar - [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. - [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. -## Resources +## Related topics - [Wiki settings for administrators](../../../administration/wikis/index.md) - [Project wikis API](../../../api/wikis.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 11b570f19e5..3c82e544e26 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -13,7 +13,7 @@ code are saved in projects, and most features are in the scope of projects. You can explore other popular projects available on GitLab. To explore projects: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Explore projects**. GitLab displays a list of projects, sorted by last updated date. To view @@ -25,12 +25,27 @@ By default, `/explore` is visible to unauthenticated users. However, if the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) is restricted, `/explore` is visible only to signed-in users. +## Explore topics + +You can explore popular project topics available on GitLab. To explore project topics: + +1. On the top bar, select **Menu > Projects**. +1. Select **Explore topics**. + +GitLab displays a list of topics sorted by the number of associated projects. +To view projects associated with a topic, select a topic from the list. + +You can assign topics to a project on the [Project Settings page](settings/index.md#topics). + +If you're an instance administrator, you can administer all project topics from the +[Admin Area's Topics page](../admin_area/index.md#administering-topics). + ## Create a project To create a project in GitLab: -1. In your dashboard, click the green **New project** button or use the plus - icon in the navigation bar. This opens the **New project** page. +1. In your dashboard, select **New project** or use the **New...** **{plus-square}** icon +on the top bar. The **New project** page opens. 1. On the **New project** page, choose if you want to: - Create a [blank project](#blank-projects). - Create a project using one of the available [project templates](#project-templates). @@ -213,7 +228,7 @@ To star a project: To view your 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: |
