diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 16:18:24 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 16:18:24 +0300 |
| commit | 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c (patch) | |
| tree | 4dcc884cf6d81db44adae4aa99f8ec1233a41f55 /doc/user/project | |
| parent | 744144d28e3e7fddc117924fef88de5d9674fe4c (diff) | |
Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42
Diffstat (limited to 'doc/user/project')
75 files changed, 1124 insertions, 655 deletions
diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index cac283f6f18..b4723294438 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -26,7 +26,7 @@ percentage of users are affected and the change can either be fixed or quickly reverted. Leveraging [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments), visualize your canary -deployments right inside the [Deploy Board](deploy_boards.md), without the need to leave GitLab. +deployments right inside the [deploy board](deploy_boards.md), without the need to leave GitLab. ## Use cases @@ -47,9 +47,9 @@ this document. ## Enabling Canary Deployments -Canary deployments require that you properly configure Deploy Boards: +Canary deployments require that you properly configure deploy boards: -1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards). +1. Follow the steps to [enable deploy boards](deploy_boards.md#enabling-deploy-boards). 1. To track canary deployments you need to label your Kubernetes deployments and pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy) template for canary deployments that GitLab provides. @@ -61,13 +61,13 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes, Deploy Boards clearly mark canary pods, enabling +As the pipeline executes, deploy boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. -Canary deployments are marked with a yellow dot in the Deploy Board so that you +Canary deployments are marked with a yellow dot in the deploy board so that you can easily notice them. - + ### Advanced traffic control with Canary Ingress @@ -104,17 +104,17 @@ Here's an example setup flow from scratch: #### How to check the current traffic weight on a Canary Ingress -1. Visit the [Deploy Board](../../user/project/deploy_boards.md). +1. Visit the [deploy board](../../user/project/deploy_boards.md). 1. View the current weights on the right.  #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight within your environment's Deploy Board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), +You can change the traffic weight within your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). -To use your [Deploy Board](../../user/project/deploy_boards.md): +To use your [deploy board](../../user/project/deploy_boards.md): 1. Navigate to **Deployments > Environments** for your project. 1. Set the new weight with the dropdown on the right side. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 7d006247177..f7dd24fcfad 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: -Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). @@ -48,7 +48,7 @@ To create a new EKS cluster: 1. Go to your: - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin > Kubernetes**, for an instance-level cluster. + - **Menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. @@ -166,7 +166,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](index.md#supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../infrastructure/clusters/connect/index.md#supported-cluster-versions) for your cluster. | | Key pair name | The [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -240,7 +240,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. In GitLab, on the top bar, select **Menu >** **{admin}** **Admin > Settings > General** and expand the **Amazon EKS** section. +1. In GitLab, on the top bar, select **Menu > Admin > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. 1. Enter your **Account ID**. 1. Enter your [access key and ID](#eks-access-key-and-id). diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index efd480fa3ce..505c493de4e 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,11 +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 --- -# Add an existing Kubernetes cluster +# Connect existing clusters through cluster certificates If you have an existing Kubernetes cluster, you can add it to a project, group, or instance and benefit from the integration with GitLab. +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)** + ## Prerequisites See the prerequisites below to add existing clusters to GitLab. @@ -61,7 +67,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + 1. **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Add existing cluster** tab and fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. @@ -211,7 +217,8 @@ integration to work properly. WARNING: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a -[security concern](index.md#security-implications), and may not be desirable. +[security concern](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates), +and may not be desirable. To effectively disable RBAC, global permissions can be applied granting full access: diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a454b4dff99..78d4bce737d 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. WARNING: -Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). @@ -62,7 +62,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Click **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index fba02183be5..4f2bc5526e0 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -9,11 +9,9 @@ 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 the certificate-based method -is deprecated and no longer recommended. Kubernetes cluster, similar to any other -infrastructure, should be created, updated, maintained using [Infrastructure as Code](../../infrastructure/index.md). -GitLab is developing a built-in capability to create clusters with Terraform. -You can follow along in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6049). +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). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -30,29 +28,38 @@ in a few clicks. ## Create new cluster -> The certificate-based method for creating clusters from GitLab was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. + +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +to **safely create new clusters from GitLab**. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/index.md) -to **safely create your new cluster from GitLab**. +Creating clusters from GitLab using cluster certificates is still available on the +GitLab UI but was **deprecated** in GitLab 14.0 and is scheduled for removal in +GitLab 15.0. We don't recommend using this method. -The certificate-based method is **deprecated** and scheduled for removal in -GitLab 15.0. However, you can still use it until then. Through -this method, you can host your cluster in EKS, GKE, on premises, and with other -providers. To host them on premises and with other providers, -use either the EKS or GKE method to guide you through and enter your cluster's -settings manually: +You can create a new cluster hosted in EKS, GKE, on premises, and with other +providers using cluster certificates: - [New cluster hosted on Google Kubernetes Engine (GKE)](add_gke_clusters.md). - [New cluster hosted on Amazon Elastic Kubernetes Service (EKS)](add_eks_clusters.md). +To host them on premises and with other providers, you can use Terraform +or your preferred tool of choice to create and connect a cluster with GitLab. +The [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs/resources/project_cluster) +supports connecting existing clusters using the certificate-based connection method. + ## Add existing cluster -If you already have a cluster and want to integrate it with GitLab, see how to -[add an existing cluster](add_existing_cluster.md). +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +to connect your cluster to GitLab. + +Alternatively, you can [add an existing cluster](add_existing_cluster.md) +through the certificate-based method, but we don't recommend using this method for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). ## Configure your cluster -As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to configure your cluster. +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) +to configure your cluster. ## Disable a cluster @@ -62,7 +69,7 @@ one to GitLab, the cluster connection to GitLab becomes enabled. To disable it: 1. Go to your: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). 1. Click **Save changes**. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index fdd65d70242..54141fe1103 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,7 +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 --- -# Deploy to a Kubernetes cluster +# Deploy to a Kubernetes cluster with cluster certificates + +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)** A Kubernetes cluster can be the destination for a deployment job. If diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a0efea267f0..791dc90cad5 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -16,10 +16,6 @@ We offer extensive integrations to help you connect and manage your Kubernetes c Read through this document to get started. -## Clusters infrastructure - -Use [Infrastructure as Code](../../infrastructure) to create and manage your clusters with the GitLab integration with Terraform. - ## Benefit from the GitLab-Kubernetes integration Using the GitLab-Kubernetes integration, you can benefit of GitLab @@ -30,76 +26,18 @@ features such as: - Use [role-based or attribute-based access controls](cluster_access.md). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). - Connect GitLab to in-cluster applications using [cluster integrations](../../clusters/integrations.md). -- Use [Deploy Boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. +- Use [deploy boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. - Use [Canary deployments](../canary_deployments.md) to update only a portion of your fleet with the latest version of your application. - View your [Kubernetes podlogs](kubernetes_pod_logs.md) directly in GitLab. - Connect to your cluster through GitLab [web terminals](deploy_to_cluster.md#web-terminals-for-kubernetes-clusters). ## Supported cluster versions -GitLab is committed to support at least two production-ready Kubernetes minor -versions at any given time. We regularly review the versions we support, and -provide a three-month deprecation period before we remove support of a specific -version. The range of supported versions is based on the evaluation of: - -- The versions supported by major managed Kubernetes providers. -- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). - -GitLab supports the following Kubernetes versions, and you can upgrade your -Kubernetes version to any supported version at any time: - -- 1.19 (support ends on February 22, 2022) -- 1.18 (support ends on November 22, 2021) -- 1.17 (support ends on September 22, 2021) -- 1.16 (support ends on July 22, 2021) -- 1.15 (support ends on May 22, 2021) - -Some GitLab features may support versions outside the range provided here. - -## Add and remove clusters - -You can create new or add existing clusters to GitLab: - -- On the project-level, to have a cluster dedicated to a project. -- On the [group level](../../group/clusters/index.md), to use the same cluster across multiple projects within your group. -- On the [instance level](../../instance/clusters/index.md), to use the same cluster across multiple groups and projects. **(FREE SELF)** - -To create new clusters, use one of the following methods: - -- [Infrastructure as Code](../../infrastructure/index.md) (**recommended**). -- [Cluster certificates](add_remove_clusters.md) (**deprecated**). - -You can also [add existing clusters](add_existing_cluster.md) to GitLab. - -## View your clusters - -To view your project-level Kubernetes clusters, to go **Infrastructure > Kubernetes clusters** -from your project. On this page, you can add a new cluster -and view information about your existing clusters, such as: - -- Nodes count. -- Rough estimates of memory and CPU usage. - -## Configuring your Kubernetes cluster - -Use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to safely -configure your clusters. Otherwise, there are [security implications](#security-implications). - -### Security implications - -WARNING: -The whole cluster security is based on a model where [developers](../../permissions.md) -are trusted, so **only trusted users should be allowed to control your clusters**. - -The default cluster configuration grants access to a wide set of -functionalities needed to successfully build and deploy a containerized -application. Bear in mind that the same credentials are used for all the -applications running on the cluster. +See the [Kubernetes clusters versions supported by GitLab](../../infrastructure/clusters/connect/index.md#supported-cluster-versions). -## Multiple Kubernetes clusters +## Connect your cluster to GitLab -See how to associate [multiple Kubernetes clusters](multiple_kubernetes_clusters.md) -with your GitLab project. +Learn how to [create new and connect existing clusters to GitLab](../../infrastructure/clusters/connect/index.md). ## Cluster integrations diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 7a9c7eb423d..eb0e8d0e91c 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -46,15 +46,15 @@ a [metrics dashboard](../../../operations/metrics/index.md) and select **View lo [permissions](../../permissions.md#project-members-permissions) in the project. 1. To navigate to the **Log Explorer** from the sidebar menu, go to **Monitor > Logs** ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.). -1. To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md): +1. To navigate to the **Log Explorer** from a specific pod on a [deploy board](../deploy_boards.md): 1. Go to **Deployments > Environments** and find the environment which contains the desired pod, like `production`. 1. On the **Environments** page, you should see the status of the environment's - pods with [Deploy Boards](../deploy_boards.md). + pods with [deploy boards](../deploy_boards.md). 1. When mousing over the list of pods, GitLab displays a tooltip with the exact pod name and status. -  +  1. Click on the desired pod to display the **Log Explorer**. ### Logs view diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 62010bb7802..1940cf229b8 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -137,7 +137,7 @@ Network Policies can be managed through GitLab in one of two ways: - Management through a YAML file in each application's project (for projects using Auto DevOps). For more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more - information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only). + information, see the [Container Network Policy documentation](../../../../application_security/policies/index.md#container-network-policy) (Ultimate only). Each method has benefits and drawbacks: @@ -167,7 +167,7 @@ hubble: ``` Additional information about the statistics page is available in the -[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy). +[documentation that describes the Threat Management UI](../../../../application_security/policies/index.md#container-network-policy). ## Forwarding logs to a SIEM diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index b2054c4befb..7357fc850e5 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -63,7 +63,7 @@ information. Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the pre-loaded demo runbook. -1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-oauth2-authentication-service-provider). +1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-an-oauth-20-authentication-service-provider). 1. When [installing JupyterHub with Helm](https://zero-to-jupyterhub.readthedocs.io/en/latest/jupyterhub/installation.html), use the following values ```yaml diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index ec22f71157f..fb32579f40e 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -4,9 +4,10 @@ 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 --- -# Serverless **(FREE)** +# Serverless (DEPRECATED) **(FREE)** -> Introduced in GitLab 11.5. +> - Introduced in GitLab 11.5. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3. WARNING: Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). @@ -316,7 +317,7 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/python3` | OpenFaaS | | `openfaas/classic/ruby` | OpenFaaS | -After the `gitlab-ci.yml` template has been added and the `serverless.yml` file +After the `.gitlab-ci.yml` template has been added and the `serverless.yml` file has been created, pushing a commit to your project results in a CI pipeline being executed which deploys each function as a Knative service. After the deploy stage has finished, additional details for the function display diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 64a5515136b..05f026cca18 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 **(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. @@ -16,7 +16,7 @@ type: howto, reference > This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in > GitLab 13.12. -GitLab Deploy Boards offer a consolidated view of the current health and +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 of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use @@ -28,23 +28,23 @@ environments by using [Auto DevOps](../../topics/autodevops/index.md). ## Overview -With Deploy Boards you can gain more insight into deploys with benefits such as: +With deploy boards you can gain more insight into deploys with benefits such as: - Following a deploy from the start, not just when it's done - Watching the rollout of a build across multiple servers - Finer state detail (Succeeded, Running, Failed, Pending, Unknown) - See [Canary Deployments](canary_deployments.md) -Here's an example of a Deploy Board of the production environment. +Here's an example of a deploy board of the production environment. - + The squares represent pods in your Kubernetes cluster that are associated with the given environment. Hovering above each square you can see the state of a deploy rolling out. The percentage is the percent of the pods that are updated to the latest release. -Since Deploy Boards are tightly coupled with Kubernetes, there is some required +Since deploy boards are tightly coupled with Kubernetes, there is some required knowledge. In particular, you should be familiar with: - [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/) @@ -54,7 +54,7 @@ knowledge. In particular, you should be familiar with: ## Use cases -Since the Deploy Board is a visual representation of the Kubernetes pods for a +Since the deploy board is a visual representation of the Kubernetes pods for a specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the @@ -73,9 +73,9 @@ specific environment, there are a lot of use cases. To name a few: list, find the [Review App](../../ci/review_apps/index.md) you're interested in, and click the manual action to deploy it to staging. -## Enabling Deploy Boards +## Enabling deploy boards -To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: +To display the deploy boards for a specific [environment](../../ci/environments/index.md) you should: 1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage. @@ -83,7 +83,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ NOTE: If you're using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards don't render + instead of `DeploymentConfiguration`. Otherwise, the deploy boards don't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). @@ -114,17 +114,17 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**: -  +  Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Deployments > Environments**. -Deploy Boards are visible by default. You can explicitly click +Deploy boards are visible by default. You can explicitly click the triangle next to their respective environment name in order to hide them. ### Example manifest file -The following example is an extract of a Kubernetes manifest deployment file, using the two annotations `app.gitlab.com/env` and `app.gitlab.com/app` to enable the **Deploy Boards**: +The following example is an extract of a Kubernetes manifest deployment file, using the two annotations `app.gitlab.com/env` and `app.gitlab.com/app` to enable the **deploy boards**: ```yaml apiVersion: apps/v1 diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 1b9a17ee071..e9a38f91677 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -121,7 +121,7 @@ repositories to secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 70363b67c88..1798aa0c1c6 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -181,7 +181,7 @@ To pull images from the Dependency Proxy, you must: 1. Create a group deploy token with both `read_registry` and `write_registry` scopes. 1. Take note of your `username` and `token`. -1. Follow the Depenency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). +1. Follow the Dependency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). ### GitLab deploy token diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 72ef88b5fab..5b19a54bd91 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -116,7 +116,7 @@ Only instance administrators can set instance-level templates. To set the instance-level description template repository: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown, select your template project as the template repository at instance level. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 802eb3efc51..cda018a0c37 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -16,18 +16,18 @@ Import your projects from Bitbucket Cloud to GitLab with minimal effort. The Bitbucket importer can import: -- Repository description (GitLab 7.7+) -- Git repository data (GitLab 7.7+) -- Issues (GitLab 7.7+) -- Issue comments (GitLab 8.15+) -- Pull requests (GitLab 8.4+) -- Pull request comments (GitLab 8.15+) -- Milestones (GitLab 8.15+) -- Wiki (GitLab 8.15+) +- Repository description +- Git repository data +- Issues +- Issue comments +- Pull requests +- Pull request comments +- Milestones +- Wiki When importing: -- References to pull requests and issues are preserved (GitLab 8.7+). +- References to pull requests and issues are preserved. - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 1ab343d75fb..4443ae902fb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -31,13 +31,18 @@ each imported repository maintains visibility level unless that [visibility level is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. -The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `gitlab.com/customer-success`. You can do some bulk actions to move projects to different namespaces in the rails console. +The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or +`gitlab.com/customer-success`. You can do some bulk actions to move projects to +different namespaces in the rails console. -This process does not migrate or import any types of groups or organizations from GitHub to GitLab. +This process does not migrate or import any types of groups or organizations +from GitHub to GitLab. ## Use cases -The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. +The steps you take depend on whether you are importing from GitHub.com or +GitHub Enterprise. The steps also depend on whether you are importing to GitLab.com or +self-managed GitLab instance. - If you're importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). We do not recommend @@ -49,12 +54,14 @@ The steps you take depend on whether you are importing from GitHub.com or GitHub - If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. You can use the [Import API](../../../api/import.md). +- If you're importing from GitHub.com to your self-managed GitLab instance, + setting up GitHub integration is not required. You can use the [Import API](../../../api/import.md). ## How it works -When issues and pull requests are being imported, the importer attempts to find their GitHub authors and -assignees in the database of the GitLab instance (note that pull requests are called "merge requests" in GitLab). +When issues and pull requests are being imported, the importer attempts to find +their GitHub authors and assignees in the database of the GitLab instance (note +that pull requests are called "merge requests" in GitLab). For this association to succeed, each GitHub author and assignee in the repository must meet one of the following conditions prior to the import: @@ -64,12 +71,13 @@ must meet one of the following conditions prior to the import: that matches their GitLab account's email address. NOTE: - GitLab content imports that use GitHub accounts require that the GitHub public-facing - email address is populated so that all comments and contributions are properly mapped - to the same user in GitLab. GitHub Enterprise (on premise) does not require this field - to be populated to use the product, so you may need to add it on existing GitHub Enterprise - accounts for imported content to be properly mapped to the user in the new system. - Refer to GitHub documentation for instructions on how to add that address. + GitLab content imports that use GitHub accounts require that the GitHub + public-facing email address is populated so that all comments and + contributions are properly mapped to the same user in GitLab. GitHub + Enterprise (on premise) does not require this field to be populated to use the + product, so you may have to add it on existing accounts for the imported + content to be properly mapped to the user in the new system. Refer to GitHub + documentation for instructions on how to add this email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original @@ -132,7 +140,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Copy the token hash. 1. Go back to GitLab and provide the token to the GitHub importer. 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. - Once done, you'll be taken to the importer page to select the repositories to import. + Once done, you are taken to the importer page to select the repositories to import. To use a newer personal access token in imports after previously performing these steps, sign out of your GitLab account and sign in again, or revoke the older personal access token in GitHub. @@ -152,7 +160,7 @@ your GitHub repositories are listed.  -## Mirroring and pipeline status sharing +## Mirror a repository and share pipeline status Depending on your GitLab tier, [repository mirroring](../repository/repository_mirroring.md) can be set up to keep your imported repository in sync with its GitHub copy. @@ -169,7 +177,7 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances NOTE: -Administrator access to the GitLab server is required. +An administrator role on the GitLab server is required for this process. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: @@ -183,4 +191,52 @@ servers. For 4 servers with 8 cores this means you can import up to 32 objects ( Reducing the time spent in cloning a repository can be done by increasing network throughput, CPU capacity, and disk performance (by using high performance SSDs, for example) of the disks that store the Git repositories (for your GitLab instance). -Increasing the number of Sidekiq workers will *not* reduce the time spent cloning repositories. +Increasing the number of Sidekiq workers does *not* reduce the time spent cloning repositories. + +## Alternative way to import notes and diff notes + +When GitHub Importer runs on extremely large projects not all notes & diff notes can be imported due to GitHub API `issues_comments` & `pull_requests_comments` endpoints limitation. +Not all pages can be fetched due to the following error coming from GitHub API: `In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.`. + +An alternative approach for importing notes and diff notes is available behind a feature flag. + +Instead of using `issues_comments` and `pull_requests_comments`, use individual resources `issue_comments` and `pull_request_comments` instead to pull notes from one object at a time. +This allows us to carry over any missing comments, however it increases the number of network requests required to perform the import, which means its execution takes a longer time. + +To use the alternative way of importing notes, the `github_importer_single_endpoint_notes_import` feature flag must be enabled on the group project is being imported into. + +Start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +group = Group.find_by_full_path('my/group/fullpath') + +# Enable +Feature.enable(:github_importer_single_endpoint_notes_import, group) + +# Disable +Feature.disable(:github_importer_single_endpoint_notes_import, group) +``` + +## Reduce GitHub API request objects per page + +Some GitHub API endpoints may return a 500 or 502 error for project imports from large repositories. +To reduce the chance of such errors, you can enable the feature flag +`github_importer_lower_per_page_limit` in the group project importing the data. This reduces the +page size from 100 to 50. + +To enable this feature flag, start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +and run the following `enable` command: + +```ruby +group = Group.find_by_full_path('my/group/fullpath') + +# Enable +Feature.enable(:github_importer_lower_per_page_limit, group) +``` + +To disable the feature, run this command: + +```ruby +# Disable +Feature.disable(:github_importer_lower_per_page_limit, group) +``` diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index dcc41c6c85e..65e1eafa477 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -76,7 +76,7 @@ a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use the restore method to switch between different operating system distributions or versions, as long -as the same GitLab version [is available for installation](https://docs.gitlab.com/omnibus/package-information/deprecated_os.md). +as the same GitLab version [is available for installation](../../../administration/package_information/deprecated_os.md). To instead merge two self-managed GitLab instances together, use the instructions in [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 3e0faec0a49..c6992422733 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your Jira project issues to GitLab **(PREMIUM)** +# Import your Jira project issues to GitLab **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 668a0dffd32..8c81af418a0 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -22,8 +22,8 @@ Projects include the following [features](https://about.gitlab.com/features/): **Repositories:** - [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue Boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. + - [Issue boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. - [Repositories](repository/index.md): Host your code in a fully-integrated platform. - [Branches](repository/branches/index.md): Use Git branching strategies to collaborate on code. @@ -41,8 +41,8 @@ Projects include the following [features](https://about.gitlab.com/features/): **Issues and merge requests:** - [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue Boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. + - [Issue boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. - [Merge Requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before @@ -141,7 +141,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Threads](../../api/discussions.md) - [General](../../api/projects.md) - [Import/export](../../api/project_import_export.md) -- [Issue Board](../../api/boards.md) +- [Issue board](../../api/boards.md) - [Labels](../../api/labels.md) - [Markdown](../../api/markdown.md) - [Merge Requests](../../api/merge_requests.md) diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 6b342392bdf..4908d21e764 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides an integration for updating the pipeline statuses on GitHub. This is especially useful if using GitLab for CI/CD only. -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirroring-and-pipeline-status-sharing) +This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) and is automatically configured on [GitHub import](../../../integration/github.md).  diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differindex 7928fb7d495..8acae659fb4 100644 --- a/doc/user/project/integrations/img/slack_setup.png +++ b/doc/user/project/integrations/img/slack_setup.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/index.md b/doc/user/project/integrations/index.md index 6f86098b33d..ac6e18e8e6a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -17,8 +17,8 @@ For more information, read the [overview of integrations](overview.md) or learn how to manage your integrations: - *For GitLab 13.3 and later,* read [Project integration management](../../admin_area/settings/project_integration_management.md). -- *For GitLab 13.2 and earlier,* read [Service Templates](services_templates.md), - which are deprecated and [scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +- *For GitLab 13.2 and earlier,* read [Integration Management](../../admin_area/settings/project_integration_management.md), + which replaced the deprecated Service Templates [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) in GitLab 14.0. ## Project webhooks diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5b5feb73b69..8027cc1c61e 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -22,7 +22,7 @@ on your configuration: - **Omnibus GitLab installations**: Mattermost is bundled with [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the - [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). + [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the [automated configuration](#automated-configuration). - **For all other installations**, use the [manual configuration](#manual-configuration). @@ -68,7 +68,7 @@ information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. 1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 13def74450c..a6f739c6408 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -12,8 +12,10 @@ functionality to GitLab. ## Accessing integrations -You can find the available integrations under your project's -**Settings > Integrations** page. +To find the available integrations for your project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. There are more than 20 integrations to integrate with. Select the one that you want to configure. @@ -60,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{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/services_templates.md b/doc/user/project/integrations/services_templates.md deleted file mode 100644 index 37df48c75f8..00000000000 --- a/doc/user/project/integrations/services_templates.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../admin_area/settings/project_integration_management.md' -remove_date: '2021-09-09' ---- - -This document was moved to [another location](../../admin_area/settings/project_integration_management.md). - -<!-- This redirect file can be deleted after <2021-09-09>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5db4e839b54..a38d2157699 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -10,27 +10,27 @@ The Slack notifications service enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -You can also use Slack slash commands to control GitLab inside Slack. This is the -separately configured [Slack slash commands](slack_slash_commands.md). +You can also use [Slack slash commands](slack_slash_commands.md) +to control GitLab from Slack. Slash commands are configured separately. -## Slack configuration +## Configure Slack 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). 1. Identify the Slack channel where notifications should be sent to by default. Select **Add Incoming WebHooks integration** to add the configuration. -1. Copy the **Webhook URL**, which is used later in the GitLab configuration. +1. Copy the **Webhook URL** to use later when you configure GitLab. -## GitLab configuration +## Configure GitLab 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. -1. Select the **Slack notifications** integration to configure it. +1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab event to send to Slack as a notification. For a full list, see - [Triggers available for Slack notifications](#triggers-available-for-slack-notifications). + [Triggers for Slack notifications](#triggers-for-slack-notifications). By default, messages are sent to the channel you configured during - [Slack integration](#slack-configuration). + [Slack configuration](#configure-slack). 1. (Optional) To send messages to a different channel, multiple channels, or as a direct message: - *To send messages to channels,* enter the Slack channel names, separated by @@ -40,38 +40,39 @@ separately configured [Slack slash commands](slack_slash_commands.md). NOTE: Usernames and private channels are not supported. -1. In **Webhook**, enter the webhook URL you copied from the previous - [Slack integration](#slack-configuration) step. +1. In **Webhook**, enter the webhook URL you copied in the + [Slack configuration](#configure-slack) step. 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 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 in order to trigger a +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 notification. 1. Select **Test settings** to verify your information, and then select **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. -### Triggers available for Slack notifications +## Triggers for Slack notifications The following triggers are available for Slack notifications: -| Trigger | Description | -|------------------------|-------------| -| **Push** | Triggered by a push to the repository. | -| **Issue** | Triggered when an issue is created, updated, or closed. | -| **Confidential issue** | Triggered when a confidential issue is created, updated, or closed. | -| **Merge request** | Triggered when a merge request is created, updated, or merged. | -| **Note** | Triggered when someone adds a comment. | -| **Confidential note** | Triggered when someone adds a confidential note. | -| **Tag push** | Triggered when a new tag is pushed to the repository. | -| **Pipeline** | Triggered when a pipeline status changes. | -| **Wiki page** | Triggered when a wiki page is created or updated. | -| **Deployment** | Triggered when a deployment starts or finishes. | -| **Alert** | Triggered when a new, unique alert is recorded. | +| Trigger name | Trigger event | +| ------------------------ | ------------------------------------------------------ | +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| **Vulnerability** | **(ULTIMATE)** A new, unique vulnerability is recorded. | ## Troubleshooting @@ -81,45 +82,48 @@ for errors relating to your Slack service. ### Something went wrong on our end -This is a generic error shown in the GitLab UI and does not mean much by itself. +You might get this generic error message in the GitLab UI. Review [the logs](../../../administration/logs.md#productionlog) to find -an error message and keep troubleshooting from there. +the error message and keep troubleshooting from there. ### `certificate verify failed` -You may see an entry similar to the following in your Sidekiq log: +You might see an entry like the following in your Sidekiq log: ```plaintext 2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} ``` -This is probably a problem either with GitLab communicating with Slack, or GitLab -communicating with itself. The former is less likely, as Slack's security certificates -should _hopefully_ always be trusted. We can establish which we're dealing with by using -the below rails console script. +This issue occurs when there is a problem with GitLab communicating with Slack, +or GitLab communicating with itself. +The former is less likely, as Slack security certificates should always be trusted. -```shell -# start a rails console: -sudo gitlab-rails console -e production +To view which of these problems is the cause of the issue: -# or for source installs: -bundle exec rails console -e production -``` +1. Start a Rails console: -```ruby -# run this in the Rails console -# replace <SLACK URL> with your actual Slack URL -result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + ```shell + sudo gitlab-rails console -e production -# replace <GITLAB URL> with your actual GitLab URL -result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 -``` + # for source installs: + bundle exec rails console -e production + ``` + +1. Run the following commands: + + ```ruby + # replace <SLACK URL> with your actual Slack URL + result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + + # replace <GITLAB URL> with your actual GitLab URL + result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 + ``` -If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +If GitLab does not trust HTTPS connections to itself, +[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -If GitLab is not trusting connections to Slack, then the GitLab -OpenSSL trust store is incorrect. Some typical causes: +If GitLab does not trust connections to Slack, +the GitLab OpenSSL trust store is incorrect. Typical causes are: - Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`. - Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index dfebf9a1123..066a2f83753 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -8,27 +8,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 8.15. -Slack slash commands allow you to control GitLab and view content right inside -Slack, without having to leave it. This requires configurations in both Slack and GitLab. +If you want to control and view GitLab content while you're +working in Slack, you can use Slack slash commands. +To use Slack slash commands, you must configure both Slack and GitLab. -GitLab can also send events (e.g., `issue created`) to Slack as notifications. -This is the separately configured [Slack Notifications Service](slack.md). +GitLab can also send events (for example, `issue created`) to Slack as notifications. +The [Slack notifications service](slack.md) is configured separately. NOTE: -For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. +For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. -## Configuration +## Configure GitLab and Slack -1. Slack slash commands are scoped to a project. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Slack slash commands** integration to configure it. This page contains required information to complete the configuration in Slack. Leave this browser tab open. -1. Open a new browser tab and sign in to your Slack team. [Start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). -1. Enter a trigger term. We suggest you use the project name. Click **Add Slash Command Integration**. -1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. In particular, the URL needs to be copied and pasted. Click **Save Integration** to complete the configuration in Slack. -1. While still on the Slack configuration page, copy the **token**. Go back to the GitLab browser tab and paste in the **token**. -1. Ensure that the **Active** toggle is enabled and click **Save changes** to complete the configuration in GitLab. +Slack slash command [integrations](overview.md#accessing-integrations) +are scoped to a project. - +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Slack slash commands**. Leave this browser tab open. +1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). +1. Enter a trigger command. We suggest you use the project name. + Select **Add Slash Command Integration**. +1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. + In particular, make sure you copy and paste the **URL**. -## Usage +  -You can now use the [Slack slash commands](../../../integration/slash_commands.md). +1. On the Slack configuration page, select **Save Integration** and copy the **Token**. +1. Go back to the GitLab configuration page and paste in the **Token**. +1. Ensure the **Active** checkbox is selected and select **Save changes**. + +## Slash commands + +You can now use the available [Slack slash commands](../../../integration/slash_commands.md). diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 3632fdf0e0c..de152aabde5 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,7 @@ notifications: 1. Navigate to: - **Settings > Integrations** in a project to enable the integration at the project level. - **Settings > Integrations** in a group to enable the integration at the group level. - - On the top bar, select **Menu >** **{admin}** **Admin**. Then, in the left sidebar, + - On the top bar, select **Menu > Admin**. Then, in the left sidebar, select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..ab8a7829139 --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,40 @@ +--- +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)** + +[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 0c624d7df01..4d1805e3d31 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards **(FREE)** +# Issue boards **(FREE)** -The GitLab Issue Board is a software project management tool used to plan, +The issue board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. @@ -46,7 +46,7 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of -the Issue Board feature. +the issue board feature. ## Multiple issue boards @@ -70,7 +70,7 @@ GitLab automatically loads the last board you visited. To create a new issue board: -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click the dropdown with the current board name in the upper left corner of the issue boards page. 1. Click **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. @@ -78,7 +78,7 @@ To create a new issue board: To delete the currently active issue board: -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click the dropdown with the current board name in the upper left corner of the issue boards page. 1. Click **Delete board**. 1. Click **Delete** to confirm. @@ -195,7 +195,7 @@ card includes: ## Permissions 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. +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 @@ -229,8 +229,7 @@ and vice versa. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. > - [Deployed behind a feature flag](../feature_flags.md), enabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) in GitLab 14.1 -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** +> - [Feature flag `graphql_board_lists`](https://gitlab.com/gitlab-org/gitlab/-/issues/248908) removed in GitLab 14.3 There can be [risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). @@ -271,7 +270,7 @@ clicking **View scope**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of -the Configurable Issue Board feature. +the configurable issue board feature. ### Focus mode @@ -339,14 +338,14 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - [Deployed behind the `board_new_list` and `iteration_board_lists` feature flags](../feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** +> - Enabled on GitLab.com and is ready for production use. +> - Enabled with `iteration_board_lists` flag for self-managed GitLab and is ready for production use. +> GitLab administrators can opt to [disable the feature flag](#enable-or-disable-iteration-lists-in-boards). -There can be -[risks when disabling released features](../../administration/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the `iteration_board_lists` flag](../../administration/feature_flags.md). +On GitLab.com, this feature is available. You're also able to create lists of an iteration. These are lists that filter issues by the assigned @@ -387,7 +386,7 @@ appears on the right. There you can see and edit the issue's: - Title - Assignees -- Epic **PREMIUM** +- Epic **(PREMIUM)** - Milestone - Time tracking value (view only) - Due date @@ -673,52 +672,8 @@ A few things to remember: by default. If you have more than 20 issues, start scrolling down and the next 20 appear. -### Enable or disable GraphQL-based issue boards **(FREE SELF)** - -NOTE: -When enabling GraphQL-based issue boards, you must also enable the -[new add list form](#enable-or-disable-new-add-list-form). - -It is deployed behind a feature flag that is **enabled by default** as of GitLab 14.1. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:graphql_board_lists) -``` - -To disable it: - -```ruby -Feature.disable(:graphql_board_lists) -``` - -### Enable or disable new add list form **(FREE SELF)** - -The new form for adding lists is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:board_new_list) -``` - -To disable it: - -```ruby -Feature.disable(:board_new_list) -``` - ### Enable or disable iteration lists in boards **(PREMIUM SELF)** -NOTE: -When disabling iteration lists in boards, you also need to disable the [new add list form](#enable-or-disable-new-add-list-form). - The iteration list is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 2b07131df6e..ed6c07f2c6d 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -19,14 +19,20 @@ issue itself and the first commit related to that issue. If the issue and the code you're committing are both in the same project, add `#xxx` to the commit message, where `xxx` is the issue number. -If they are not in the same project, you can add the full URL to the issue -(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). ```shell git commit -m "this is my commit message. Ref #xxx" ``` -or +If they are in different projects, but in the same group, +add `projectname#xxx` to the commit message. + +```shell +git commit -m "this is my commit message. Ref projectname#xxx" +``` + +If they are not in the same group, you can add the full URL to the issue +(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). ```shell git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>" diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 56c219eb8c3..9842b0820e6 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -43,9 +43,9 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Cross-link issues](crosslinking_issues.md) - [Bulk edit issues](../issues/managing_issues.md) - [Sort issue lists](sorting_issue_lists.md) -- [Search for issues](../../search/index.md#filtering-issue-and-merge-request-lists) +- [Search for issues](../../search/index.md#filter-issue-and-merge-request-lists) - [Epics](../../group/epics/index.md) -- [Issue Boards](../issue_board.md) +- [Issue boards](../issue_board.md) - [Issues API](../../../api/issues.md) - [Configure an external issue tracker](../../../integration/external-issue-tracker.md) - [Parts of an issue](issue_data_and_actions.md) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 78dc6805f2b..6bb60e5e31a 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed. ### Labels Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [GitLab Issue Board](../issue_board.md). +and they enable you to work with the [issue board](../issue_board.md). Group Labels, which allow you to use the same labels for all projects in the same group, can also be given to issues. They work exactly the same, but are immediately diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a2185c83f4d..7033b90b736 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -44,7 +44,7 @@ There are many ways to get to the New Issue form from a project's page:  -- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. +- From an **issue board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. It opens a new issue for that project, pre-labeled with its respective list.  @@ -72,7 +72,7 @@ When you're creating a new issue, these are the fields you can fill in: To visit the issue tracker for all projects in your group: 1. Go to the group dashboard. -1. In the left sidebar, select **Issues**. +1. On the left sidebar, select **Issues**. 1. In the top-right, select the **Select project to create issue** button. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. @@ -237,10 +237,10 @@ using the close button:  -You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card +You can also close an issue from the [issue boards](../issue_board.md) by dragging an issue card from its list and dropping it into the **Closed** list. - + ### Closing issues automatically diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 2681a39aeb6..aed346fb504 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -16,6 +16,7 @@ You can sort a list of issues several ways, including by: - Milestone due date - Popularity - Priority +- Title ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67234) in GitLab 14.3) - Weight The available sorting options can change based on the context of the list. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 353ce73329e..e1149b85cd5 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -59,7 +59,7 @@ In GitLab 13.11, you can optionally replace the sharing form with a modal window To share a project after enabling this feature: 1. Go to your project's page. -1. In the left sidebar, go to **Project information > Members**, and then select **Invite a group**. +1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. 1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 47744edd5ce..aff55419a88 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -61,7 +61,9 @@ GitLab displays one of these buttons after the body of the merge request: Eligible approvers can also use the `/approve` [quick action](../../../project/quick_actions.md) when adding a comment to -a merge request. +a merge request. [In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), +if a user approves a merge request and is shown in the reviewer list, a green check mark +(**{check-circle-filled}**) displays next to their name. After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index c59d5973e21..d348c00bdc2 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -97,11 +97,8 @@ a merge request. You can choose to hide or show whitespace changes: ## Mark files as viewed -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. -> - Deployed behind a feature flag, enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296674) in GitLab 14.3. When reviewing a merge request with many files multiple times, it may be useful to the reviewer to focus on new changes and ignore the files that they have already reviewed and don't want to @@ -116,25 +113,6 @@ To mark a file as viewed: Once checked, the file remains marked for that reviewer unless there are newly introduced changes to its content or the checkbox is unchecked. -### Enable or disable file views **(FREE SELF)** - -The file view feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:local_file_reviews) -``` - -To disable it: - -```ruby -Feature.disable(:local_file_reviews) -``` - ## Show merge request conflicts in diff > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index a0c3efe7143..4a2319774ac 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -11,7 +11,7 @@ GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") with a **Cherry-pick** button in merge requests and commit details. -## Cherry-picking a merge request +## Cherry-pick a merge request After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. @@ -25,7 +25,7 @@ where you can choose to either: - Cherry-pick the changes directly into the selected branch. - Create a new merge request with the cherry-picked changes. -### Cherry-pick tracking +### Track a cherry-pick > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. @@ -40,7 +40,7 @@ NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for tracking cherry-picked commits through the command line is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/202215). -## Cherry-picking a commit +## Cherry-pick a commit You can cherry-pick a commit from the commit details page: diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 6337fb1e87b..e9f1874eb96 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -56,11 +56,10 @@ See also the Code Climate list of [Supported Languages for Maintainability](http ## Code Quality in diff view **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. -> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. -> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.1. +> - [Disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0 due to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334116). +> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: @@ -276,7 +275,7 @@ might look like this example: job1: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run job1 in merge request pipelines - - if: '$CI_COMMIT_BRANCH == "master"' # Run job1 in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_BRANCH == "main"' # Run job1 in pipelines on the main branch (but not in other branch pipelines) - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` @@ -292,7 +291,7 @@ code_quality: - if: '$CODE_QUALITY_DISABLED' when: never - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Run code quality job in merge request pipelines - - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the master branch (but not in other branch pipelines) + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' # Run code quality job in pipelines on the default branch (but not in other branch pipelines) - if: '$CI_COMMIT_TAG' # Run code quality job in pipelines for tags ``` diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 6d8a128c39f..0d87a04461b 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -45,7 +45,7 @@ This template requires: - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. -- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. +- A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this. ## Configuring Fast RSpec Failure diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index b1e8d761f5c..7edc379399b 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -24,9 +24,11 @@ When a fast-forward merge is not possible, the user is given the option to rebas ## Enabling fast-forward merges -1. Navigate to your project's **Settings** and search for the 'Merge method' -1. Select the **Fast-forward merge** option -1. Hit **Save changes** for the changes to take effect +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Fast-forward merge**. +1. Select **Save changes**. Now, when you visit the merge request page, you can accept it **only if a fast-forward merge is possible**. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 46fc3ec141d..72fcd7f36b0 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -65,7 +65,7 @@ request's page at the top-right side: After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews). +- [Perform inline code reviews](reviews/index.md). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** - Preview continuous integration [pipelines on the merge request widget](widgets.md). - Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). @@ -166,10 +166,13 @@ is set for deletion, the merge request widget displays the ### Branch retargeting on merge **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) in GitLab 13.10. -> - Recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** +> - [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 @@ -203,22 +206,3 @@ This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitla - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. - -### Enable or disable branch retargeting on merge **(FREE SELF)** - -Automatically retargeting merge requests is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:retarget_merge_requests) -``` - -To disable it: - -```ruby -Feature.disable(:retarget_merge_requests) -``` diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 6c2f07d7012..b7e055ca749 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,7 +27,7 @@ important parts of the merge request:  - **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolve-a-thread)) + 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. @@ -53,7 +53,7 @@ GitLab displays open merge requests, with tabs to filter the list by open and cl  -You can [search and filter](../../search/index.md#filtering-issue-and-merge-request-lists), +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 @@ -76,6 +76,21 @@ can assign, categorize, and track progress on 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: + +- [Edit changes in the Web IDE](../web_ide/index.md) in your browser. 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 + need a fully-featured environment to both edit files, and run tests afterward. Gitpod + supports running the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit). + To use Gitpod, you must [enable Gitpod in your user account](../../../integration/gitpod.md#enable-gitpod-in-your-user-settings). +- [Push changes from the command line](../../../gitlab-basics/start-using-git.md), if you are + familiar with Git and the command line. + ## Close a merge request If you decide to permanently stop work on a merge request, @@ -130,7 +145,7 @@ For a web developer writing a webpage for your company's website: 1. You request your web designers for their implementation. 1. You request the [approval](approvals/index.md) from your manager. 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). -1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. +1. Your production team [cherry-picks](cherry_pick_changes.md) the merge commit into production. ## Related topics diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7ea785c00ea..1d892a3c2e1 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -181,7 +181,7 @@ include: review: stage: deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: http://$CI_ENVIRONMENT_SLUG.example.com script: - run_deploy_script diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index a798f2c9b85..e6fb619d365 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Reverting changes **(FREE)** +# Revert changes **(FREE)** You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") by clicking the **Revert** button in merge requests and commit details. -## Reverting a merge request +## Revert a merge request NOTE: The **Revert** button is available only for merge requests @@ -34,7 +34,7 @@ create a new merge request with the revert changes. After the merge request has been reverted, the **Revert** button is no longer available. -## Reverting a commit +## Revert a commit You can revert a commit from the commit details page: diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 61cd0d25aaf..dbf3b0180e6 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -12,9 +12,10 @@ type: index, reference [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) -to propose changes. Your team leaves [comments](../../../discussions/index.md), 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. +to propose changes. Your team leaves [comments](../../../discussions/index.md) on +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. ## Review a merge request @@ -28,7 +29,9 @@ To start your review: 1. Go to the merge request you want to review, and select the **Changes** tab. To learn more about navigating the diffs displayed in this tab, read [Changes tab in merge requests](../changes.md). -1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines + and display a comment box. In GitLab version 13.2 and later, you can + [select multiple lines](#comment-on-multiple-lines). 1. Write your first comment, and select **Start a review** below your comment:  1. Continue adding comments to lines of code, and select the appropriate button after @@ -40,7 +43,13 @@ To start your review: The comment shows the actions to perform after publication, but does not perform them until you submit your review. 1. When your review is complete, you can [submit the review](#submit-a-review). Your comments - are now visible, and any quick actions included your comments are performed. + are now visible, and any [quick actions](../../quick_actions.md) included in + your comments are performed. + +[In GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/292936), +if you [approve a merge request](../approvals/index.md#approve-a-merge-request) and +are shown in the reviewer list, a green check mark **{check-circle-filled}** +displays next to your name. ### Submit a review @@ -57,7 +66,7 @@ When you submit your review, GitLab: review comments attached. Replying to this email creates a new comment on the merge request. - Perform any quick actions you added to your review comments. -### Resolving/Unresolving threads +### Resolve or unresolve thread with a comment Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). When replying to a comment, a checkbox is displayed to resolve or unresolve @@ -72,7 +81,7 @@ comment itself.  -### Adding a new comment +### Add a new comment > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. @@ -97,7 +106,7 @@ This example shows reviewers and approval rules in a merge request sidebar:  -### Requesting a new review +### Request a new review > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. @@ -112,13 +121,6 @@ the author of the merge request can request a new review from the reviewer: GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends them a notification email. -#### Approval status - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. - -If a user in the reviewer list has approved the merge request, a green tick symbol is -shown to the right of their name. - ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -130,18 +132,7 @@ succeeded, the target branch build also succeeds after the merge. 1. In the **Merge method** section, select **Merge commit with semi-linear history**. 1. Select **Save changes**. -## Perform inline code reviews - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. - -In a merge request, you can leave comments in any part of the file being changed. -In the merge request Diff UI, you can: - -- **Comment on a single line**: Select the **{comment}** **comment** icon in the - gutter to expand the diff lines and display a comment box. -- [**Comment on multiple lines**](#comment-on-multiple-lines). - -### Comment on multiple lines +## Comment on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 8ee068531c8..4027ec08234 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -46,7 +46,7 @@ branch. The [Developer role](../../../permissions.md) is required to do so. ## Multi-line suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single suggestion within merge request diff threads by adjusting the range offsets. The diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 2842c084bc5..c3fc2fa871f 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -12,8 +12,6 @@ type: reference, concepts With squash and merge you can combine all your merge request's commits into one and retain a clean history. -## Overview - Squashing lets you tidy up the commit history of a branch when accepting a merge request. It applies all of the changes in the merge request as a single commit, and then merges that commit using the merge method set for the project. @@ -58,7 +56,7 @@ meaningful commit messages and: - It's simpler to [revert](revert_changes.md) if necessary. - The merged branch retains the full commit history. -## Enabling squash for a merge request +## Enable squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed on the merge request form. Users can select or clear the checkbox when they @@ -98,7 +96,7 @@ it. This is because squashing is only available when accepting a merge request, so a merge request may need to be rebased before squashing, even though squashing can itself be considered equivalent to rebasing. -## Squash Commits Options +## Squash commits options > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. > - Deployed behind a feature flag, disabled by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 1576b639a76..399d7958bbf 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -125,7 +125,7 @@ the status checks as `pending`:  -After GitLab [receives a response](../../../api/status_checks.md#set-approval-status-of-an-external-status-check) +After GitLab [receives a response](../../../api/status_checks.md#set-status-of-an-external-status-check) from the external status check, the widget updates accordingly. NOTE: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index ce8bfa2d054..813e3c1c9ce 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -24,7 +24,8 @@ Collecting the coverage information is done via GitLab CI/CD's [artifacts reports feature](../../../ci/yaml/index.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab then takes the coverage information in all the files and combines it -together. +together. Coverage files are parsed in a background job so there can be a delay +between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to @@ -129,7 +130,7 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ### JavaScript example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: @@ -147,7 +148,7 @@ test: #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -185,7 +186,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -223,7 +224,7 @@ coverage-jdk11: ### Python example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. The information isn't displayed without the conversion. This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: @@ -243,7 +244,7 @@ run tests: ### C/C++ example -The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with `gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage output file in Cobertura XML format. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 1d196de36e2..3922ee4d770 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +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 --- diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 5a688fbb485..385a4fafa7d 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -46,7 +46,7 @@ To create a GitLab Pages website: | Document | Description | | -------- | ----------- | -| [Create a `gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +| [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | | [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | | [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 532a36b2327..4b4d479e3e9 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -52,6 +52,6 @@ To sign out of your GitLab Pages website, revoke the application access token for GitLab Pages: 1. In the top menu, select your profile, and then select **Settings**. -1. In the left sidebar, select **Applications**. +1. On the left sidebar, select **Applications**. 1. Scroll to the **Authorized applications** section, find the **GitLab Pages** entry, and select its **Revoke** button. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 8ed6f214605..3deea92f56e 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -9,62 +9,58 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - In GitLab Pages, you can configure rules to forward one URL to another using [Netlify style](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) HTTP redirects. -## Supported features - -GitLab Pages only supports the -[`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), -and `.toml` files are not supported. - -Redirects are only supported at a basic level. GitLab Pages doesn't support all -[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/). - -Note that supported paths must start with a forward slash `/`. +Not all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/) +are supported. | Feature | Supported | Example | | ------- | --------- | ------- | -| Redirects (`301`, `302`) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` -| Rewrites (other status codes) | **{dotted-circle}** No | `/en/* /en/404.html 404` | -| [Splats](https://docs.netlify.com/routing/redirects/redirect-options/#splats) | **{dotted-circle}** No | `/news/* /blog/:splat` | -| Placeholders | **{dotted-circle}** No | `/news/:year/:month/:date/:slug /blog/:year/:month/:date/:slug` | +| [Redirects (`301`, `302`)](#redirects) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` +| [Rewrites (`200`)](#rewrites) | **{check-circle}** Yes | `/* / 200` | +| [Splats](#splats) | **{check-circle}** Yes | `/news/* /blog/:splat` | +| [Placeholders](#placeholders) | **{check-circle}** Yes | `/news/:year/:month/:date /blog-:year-:month-:date.html` | +| Rewrites (other than `200`) | **{dotted-circle}** No | `/en/* /en/404.html 404` | | Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | | Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | | Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | | Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | | Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | +NOTE: +The [matching behavior test cases](https://gitlab.com/gitlab-org/gitlab-pages/-/blob/master/internal/redirects/matching_test.go) +are a good resource for understanding how GitLab implements rule matching in +detail. Community contributions are welcome for any edge cases that aren't included in +this test suite! + ## Create redirects -To create redirects, -create a configuration file named `_redirects` in the `public/` directory of your -GitLab Pages site. +To create redirects, create a configuration file named `_redirects` in the +`public/` directory of your GitLab Pages site. -If your GitLab Pages site uses the default domain name (such as -`namespace.gitlab.io/projectname`) you must prefix every rule with the project name: +Note that: -```plaintext -/projectname/redirect-portal.html /projectname/magic-land.html 301 -/projectname/cake-portal.html /projectname/still-alive.html 302 -/projectname/wardrobe.html /projectname/narnia.html 302 -/projectname/pit.html /projectname/spikes.html 302 -``` +- All paths must start with a forward slash `/`. +- A default status code of `301` is applied if no [status code](#http-status-codes) is provided. +- The `_redirects` file has a file size limit of 64KB and a maximum of 1,000 rules per project. + Only the first 1,000 rules are processed. +- If your GitLab Pages site uses the default domain name (such as + `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: -If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), -no project name prefix is needed. For example, if your custom domain is `example.com`, -your `_redirect` file would look like: + ```plaintext + /projectname/wardrobe.html /projectname/narnia.html 302 + ``` -```plaintext -/redirect-portal.html /magic-land.html 301 -/cake-portal.html /still-alive.html 302 -/wardrobe.html /narnia.html 302 -/pit.html /spikes.html 302 -``` +- If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), + no project name prefix is needed. For example, if your custom domain is `example.com`, + your `_redirects` file would look like: + + ```plaintext + /wardrobe.html /narnia.html 302 + ``` ## Files override redirects @@ -81,6 +77,132 @@ GitLab doesn't support Netlify's [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. +## HTTP status codes + +A default status code of `301` is applied if no status code is provided, but +you can explicitly set your own. The following HTTP codes are supported: + +- **301**: Permanent redirect. +- **302**: Temporary redirect. +- **200**: Standard response for successful HTTP requests. Pages + serves the content in the `to` rule if it exists, without changing the URL in + the address bar. + +## Redirects + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Enabled by default in self-managed GitLab behind the [`FF_ENABLE_REDIRECTS` feature flag](#feature-flag-for-redirects). + +To create a redirect, add a rule that includes a `from` path, a `to` path, +and an [HTTP status code](#http-status-codes): + +```plaintext +# 301 permanent redirect +/old/file.html /new/file.html 301 + +# 302 temporary redirect +/old/another_file.html /new/another_file.html 302 +``` + +## Rewrites + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. +> - Enabled on GitLab.com. +> - Disabled by default in self-managed GitLab behind the [`FF_ENABLE_PLACEHOLDERS` feature flag](#feature-flag-for-rewrites). + +Provide a status code of `200` to serve the content of the `to` path when the +request matches the `from`: + +```plaintext +/old/file.html /new/file.html 200 +``` + +This status code can be used in combination with [splat rules](#splats) to dynamically +rewrite the URL. + +## Splats + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +A rule with an asterisk (`*`) in its `from` path, known as a splat, matches +anything at the start, middle, or end of the requested path. This example +matches anything after `/old/` and rewrites it to `/new/file.html`: + +```plaintext +/old/* /new/file.html 200 +``` + +### Splat placeholders + +The content matched by a `*` in a rule's `from` path can be injected into the +`to` path using the `:splat` placeholder: + +```plaintext +/old/* /new/:splat 200 +``` + +In this example, a request to `/old/file.html` serves the contents of `/new/file.html` +with a `200` status code. + +If a rule's `from` path includes multiple splats, the value of the first splat +match replaces any `:splat`s in the `to` path. + +### Splat matching behavior + +Splats are "greedy" and match as many characters as possible: + +```plaintext +/old/*/file /new/:splat/file 301 +``` + +In this example, the rule redirects `/old/a/b/c/file` to `/new/a/b/c/file`. + +Splats also match empty strings, so the previous rule redirects +`/old/file` to `/new/file`. + +### Rewrite all requests to a root `index.html` + +Single page applications (SPAs) often perform their own routing using +client-side routes. For these applications, it's important that _all_ requests +are rewritten to the root `index.html` so that the routing logic can be handled +by the JavaScript application. You can do this with a `_redirects` +rule like: + +```plaintext +/* /index.html 200 +``` + +## Placeholders + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. + +Use placeholders in rules to match portions of the requested URL and use these +matches when rewriting or redirecting to a new URL. + +A placehold is formatted as a `:` character followed by a string of letters +(`[a-zA-Z]+`) in both the `from` and `to` paths: + +```plaintext +/news/:year/:month/:date/:slug /blog/:year-:month-:date-:slug 200 +``` + +This rule instructs Pages to respond to a request for `/news/2021/08/12/file.html` by +serving the content of `/blog/2021-08-12-file.html` with a `200`. + +### Placeholder matching behavior + +Compared to [splats](#splats), placeholders are more limited in how much content +they match. Placeholders match text between forward slashes +(`/`), so use placeholders to match single path segments. + +In addition, placeholders do not match empty strings. A rule like the following +would **not** match a request URL like `/old/file`: + +```plaintext +/old/:path /new/:path +``` + ## Debug redirect rules If a redirect isn't working as expected, or you want to check your redirect syntax, visit @@ -103,8 +225,49 @@ rule 10: valid rule 11: valid ``` -## Disable redirects +## Differences from Netlify's implementation + +Most supported `_redirects` rules behave the same in both GitLab and Netlify. +However, there are some minor differences: + +- **All rule URLs must begin with a slash:** + + Netlify does not require URLs to begin with a forward slash: + + ```plaintext + # Valid in Netlify, invalid in GitLab + */path /new/path 200 + ``` + + GitLab validates that all URLs begin with a forward slash. A valid + equivalent of the previous example: + + ```plaintext + # Valid in both Netlify and GitLab + /old/path /new/path 200 + ``` +- **All placeholder values are populated:** + + Netlify only populates placeholder values that appear in the `to` path: + + ```plaintext + /old /new/:placeholder + ``` + + Given a request to `/old`: + + - Netlify redirects to `/new/:placeholder` (with a + literal `:placeholder`). + - GitLab redirects to `/new/`. + +## Features behind feature flags + +Some Pages features are behind feature flags. + +### Feature flag for redirects + +FLAG: Redirects in GitLab Pages is under development, and is deployed behind a feature flag that is **enabled by default**. @@ -126,3 +289,28 @@ For [source installations](../../../administration/pages/source.md), define the export FF_ENABLE_REDIRECTS="false" /path/to/pages/bin/gitlab-pages -config gitlab-pages.conf ``` + +### Feature flag for rewrites + +FLAG: +Rewrites in GitLab Pages is under development, and is deployed behind a feature flag +that is **disabled by default**. + +To enable rewrites, for [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable in the +[global settings](../../../administration/pages/index.md#global-settings). +Add the following line to `/etc/gitlab/gitlab.rb` and +[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure): + +```ruby +gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_PLACEHOLDERS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_PLACEHOLDERS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +``` diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 683496b4a9b..52b59d70302 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -103,6 +103,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8003)| | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | diff --git a/doc/user/project/releases/img/deploy_freeze_v13_10.png b/doc/user/project/releases/img/deploy_freeze_v13_10.png Binary files differdeleted file mode 100644 index 5c4b2d983dd..00000000000 --- a/doc/user/project/releases/img/deploy_freeze_v13_10.png +++ /dev/null diff --git a/doc/user/project/releases/img/deploy_freeze_v14_3.png b/doc/user/project/releases/img/deploy_freeze_v14_3.png Binary files differnew file mode 100644 index 00000000000..13580ac1576 --- /dev/null +++ b/doc/user/project/releases/img/deploy_freeze_v14_3.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 76b300bdd57..49b5ec2ca60 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -186,7 +186,8 @@ To subscribe to notifications for releases: ## Prevent unintentional releases by setting a deploy freeze -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. +> - The ability to delete freeze periods through the UI was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212451) in GitLab 14.3. Prevent unintended production releases during a period of time you specify by setting a [*deploy freeze* period](../../../ci/environments/deployment_safety.md). @@ -199,7 +200,7 @@ If the job that's executing is within a freeze period, GitLab CI/CD creates an e variable named `$CI_DEPLOY_FREEZE`. To prevent the deployment job from executing, create a `rules` entry in your -`gitlab-ci.yml`, for example: +`.gitlab-ci.yml`, for example: ```yaml deploy_to_production: @@ -219,11 +220,8 @@ To set a deploy freeze window in the UI, complete these steps: 1. Click **Add deploy freeze** to open the deploy freeze modal. 1. Enter the start time, end time, and timezone of the desired deploy freeze period. 1. Click **Add deploy freeze** in the modal. -1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**). -  - -WARNING: -To delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). +1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**). +  If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the complete overlapping period. @@ -394,9 +392,9 @@ upload: - if: $CI_COMMIT_TAG script: - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY} + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}" - | - curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY} + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} "${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}" release: # Caution, as of 2021-02-02 these assets links require a login, see: diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 12fd7389f21..a1ea929bb49 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -37,7 +37,7 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) To update the default branch name for an individual [project](../../index.md): -1. Sign in to GitLab as a user with the [Administrator](../../../permissions.md) role. +1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. 1. (Optional) Select the **Auto-close referenced issues on default branch** checkbox to close @@ -63,8 +63,8 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Repository**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. 1. Select **Save changes**. @@ -77,7 +77,7 @@ overrides it. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. -Administrators of groups and subgroups can configure the default branch name for a group: +Users with at least the Owner role of groups and subgroups can configure the default branch name for a group: 1. Go to the group **Settings > Repository**. 1. Expand **Default initial branch name**. @@ -128,8 +128,8 @@ renames a Git repository's (`example`) default branch. git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main ``` -1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow - the instructions to +1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) + role and follow the instructions to [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. 1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md). diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index c41b3ed8615..23d7aecc960 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -19,6 +19,11 @@ NOTE: The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. +To view a user's public GPG key, you can: + +- Go to `https://gitlab.example.com/<username>.gpg`. +- Select **View public GPG keys** (**{key}**) in the top right of the user's profile. + GPG verified tags are not supported yet. See the [further reading](#further-reading) section for more details on GPG. @@ -150,7 +155,7 @@ You can add a GPG key in your user settings: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Paste your _public_ key in the **Key** text box.  @@ -248,7 +253,7 @@ To revoke a GPG key: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Select **Revoke** next to the GPG key you want to delete. ## Removing a GPG key @@ -262,7 +267,7 @@ To remove a GPG key from your account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys**. 1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. ## Rejecting commits that are not signed **(PREMIUM)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index afdcf2a94fa..de7459e6278 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -34,7 +34,7 @@ You can [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recordin to a branch in the repository. When you use the command line, you can commit multiple times before you push. - **Commit message:** - A commit message identities what is being changed and why. + A commit message identifies what is being changed and why. In GitLab, you can add keywords to the commit message to perform one of the following actions: - **Trigger a GitLab CI/CD pipeline:** @@ -50,10 +50,10 @@ to a branch in the repository. When you use the command line, you can commit mul on their respective thread. - **Cherry-pick a commit:** In GitLab, you can - [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-pick-a-commit) from the UI. - **Revert a commit:** - [Revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) + [Revert a commit](../merge_requests/revert_changes.md#revert-a-commit) from the UI to a selected branch. - **Sign a commit:** Use GPG to [sign your commits](gpg_signed_commits/index.md). diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 76eae58b431..5a02a35fce1 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -223,13 +223,15 @@ If a repository you're interested in is located on a different server, and you w to browse its content and its activity using the GitLab interface, you can configure mirror pulling: -1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) - for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) - with the `read_repository` scope. If 2FA is enabled, this personal access +1. If your remote repository is on GitHub and you have + [two-factor authentication (2FA) configured](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa), + create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). + with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. 1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. In the **Git repository URL** field, enter a repository URL. +1. In the **Git repository URL** field, enter a repository URL. Include the username + in the URL if required: `https://MYUSERNAME@github.com/group/PROJECTNAME.git` 1. In the **Mirror direction** dropdown, select **Pull**. 1. In the **Authentication method** dropdown, select your authentication method. 1. Select from the following checkboxes, if needed: @@ -611,7 +613,7 @@ If you receive this error after creating a new project using Check if the repository owner is specified in the URL of your mirrored repository: 1. Go to your project. -1. In the left sidebar, select **Settings > Repository**. +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: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 7c115734345..17031dd29af 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -5,72 +5,82 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits and tags with X.509 **(FREE)** +# Sign commits and tags with X.509 certificates **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17773) in GitLab 12.8. [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). Personal X.509 certificates are used for authentication or signing purposes -such as SMIME, but Git also supports signing of commits and tags -with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). -The main difference is the trust anchor which is the PKI for X.509 certificates -instead of a web of trust with GPG. - -## How GitLab handles X.509 - -GitLab uses its own certificate store and therefore defines the trust chain. - +such as S/MIME (Secure/Multipurpose Internet Mail Extensions). +However, Git also supports signing of commits and tags with X.509 certificates in a +similar way as with [GPG (GnuPG, or GNU Privacy Guard)](../gpg_signed_commits/index.md). +The main difference is the way GitLab determines whether or not the developer's signature is trusted: + +- For X.509, a root certificate authority is added to the GitLab trust store. + (A trust store is a repository of trusted security certificates.) Combined with + any required intermediate certificates in the signature, the developer's certificate + can be chained back to a trusted root certificate. +- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account) + to their account. + +GitLab uses its own certificate store and therefore defines the +[trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/). For a commit or tag to be *verified* by GitLab: -- The signing certificate email must match a verified email address used by the committer in GitLab. -- The Certificate Authority has to be trusted by the GitLab instance, see also - [Omnibus install custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -- The signing time has to be within the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5) +- The signing certificate email must match a verified email address in GitLab. +- The GitLab instance must be able to establish a full [trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/) + from the certificate in the signature to a trusted certificate in the GitLab certificate store. + This chain may include intermediate certificates supplied in the signature. You may + need to add certificates, such as Certificate Authority root certificates, + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +- The signing time must be in the time range of the + [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), which is usually up to three years. -- The signing time is equal or later than commit time. - -NOTE: -Certificate revocation lists are checked on a daily basis via background worker. +- The signing time is equal to, or later than, the commit time. -NOTE: -Self signed certificates without `authorityKeyIdentifier`, -`subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We -recommend using certificates from a PKI that are in line with -[RFC 5280](https://tools.ietf.org/html/rfc5280). +If a commit's status has already been determined and stored in the database, +use the Rake task [to re-check the status](../../../../raketasks/x509_signatures.md). +Refer to the [Troubleshooting section](#troubleshooting). +GitLab checks certificate revocation lists on a daily basis with a background worker. ## Limitations +- Self-signed certificates without `authorityKeyIdentifier`, + `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We + recommend using certificates from a PKI that are in line with + [RFC 5280](https://tools.ietf.org/html/rfc5280). - If you have more than one email in the Subject Alternative Name list in your signing certificate, [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). - The `X509v3 Subject Key Identifier` (SKI) in the issuer certificate and the signing certificate [must be 40 characters long](https://gitlab.com/gitlab-org/gitlab/-/issues/332503). - If your SKI is shorter, commits will not show as verified in GitLab, and + If your SKI is shorter, commits don't show as verified in GitLab, and short subject key identifiers may also [cause errors when accessing the project](https://gitlab.com/gitlab-org/gitlab/-/issues/332464), such as 'An error occurred while loading commit signatures' and `HTTP 422 Unprocessable Entity` errors. -## Obtaining an X.509 key pair +## Configure for signed commits -If your organization has Public Key Infrastructure (PKI), that PKI provides -an S/MIME key. +To sign your commits, tags, or both, you must: -If you do not have an S/MIME key pair from a PKI, you can either create your -own self-signed one, or purchase one. MozillaZine keeps a nice collection -of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate) -and some of them generate keys for free. +1. [Obtain an X.509 key pair](#obtain-an-x509-key-pair). +1. [Associate your X.509 certificate with Git](#associate-your-x509-certificate-with-git). +1. [Sign and verify commits](#sign-and-verify-commits). +1. [Sign and verify tags](#sign-and-verify-tags). -## Associating your X.509 certificate with Git +### Obtain an X.509 key pair -To take advantage of X.509 signing, you need Git 2.19.0 or later. You can -check your Git version with: +If your organization has Public Key Infrastructure (PKI), that PKI provides +an S/MIME key. If you do not have an S/MIME key pair from a PKI, you can either +create your own self-signed pair, or purchase a pair. -```shell -git --version -``` +### Associate your X.509 certificate with Git + +To take advantage of X.509 signing, you need Git 2.19.0 or later. You can +check your Git version with the command `git --version`. If you have the correct version, you can proceed to configure Git. @@ -84,71 +94,267 @@ git config --global user.signingkey $signingkey git config --global gpg.format x509 ``` -### Windows and MacOS +#### Windows and macOS -Install [S/MIME Sign](https://github.com/github/smimesign) by downloading the -installer or via `brew install smimesign` on MacOS. +To configure Windows or macOS: -Get the ID of your certificate with `smimesign --list-keys` and set your -signing key `git config --global user.signingkey ID`, then configure X.509: +1. Install [S/MIME Sign](https://github.com/github/smimesign) by either: + - Downloading the installer. + - Running `brew install smimesign` on macOS. +1. Get the ID of your certificate by running `smimesign --list-keys`. +1. Set your signing key by running `git config --global user.signingkey ID`. +1. Configure X.509 with this command: -```shell -git config --global gpg.x509.program smimesign -git config --global gpg.format x509 -``` + ```shell + git config --global gpg.x509.program smimesign + git config --global gpg.format x509 + ``` -## Signing commits +### Sign and verify commits -After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you -can start signing your commits: +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you +can sign your commits: -1. Commit like you used to, the only difference is the addition of the `-S` flag: +1. When you create a Git commit, add the `-S` flag: ```shell git commit -S -m "feat: x509 signed commits" ``` -1. Push to GitLab and check that your commits [are verified](#verifying-commits). +1. Push to GitLab, and check that your commits are verified with the `--show-signature` flag: -If you don't want to type the `-S` flag every time you commit, you can tell Git -to sign your commits automatically: - -```shell -git config --global commit.gpgsign true -``` - -## Verifying commits + ```shell + git log --show-signature + ``` -To verify that a commit is signed, you can use the `--show-signature` flag: +1. *If you don't want to type the `-S` flag every time you commit,* run this command + for Git to sign your commits every time: -```shell -git log --show-signature -``` + ```shell + git config --global commit.gpgsign true + ``` -## Signing tags +### Sign and verify tags -After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you +After you have [associated your X.509 certificate with Git](#associate-your-x509-certificate-with-git) you can start signing your tags: -1. Tag like you used to, the only difference is the addition of the `-s` flag: +1. When you create a Git tag, add the `-s` flag: ```shell git tag -s v1.1.1 -m "My signed tag" ``` -1. Push to GitLab and check that your tags [are verified](#verifying-tags). +1. Push to GitLab and verify your tags are signed with this command: + + ```shell + git tag --verify v1.1.1 + ``` + +1. *If you don't want to type the `-s` flag every time you tag,* run this command + for Git to sign your tags each time: -If you don't want to type the `-s` flag every time you tag, you can tell Git -to sign your tags automatically: + ```shell + git config --global tag.gpgsign true + ``` -```shell -git config --global tag.gpgsign true -``` +## Resources -## Verifying tags +- [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) -To verify that a tag is signed, you can use the `--verify` flag: +## Troubleshooting + +### Re-verify commits + +GitLab stores the status of any checked commits in the database. You can use a +Rake task to [check the status of any previously checked commits](../../../../raketasks/x509_signatures.md). + +After you make any changes, run this command: ```shell -git tag --verify v1.1.1 +sudo gitlab-rake gitlab:x509:update_signatures ``` + +### Main verification checks + +The code performs +[these key checks](https://gitlab.com/gitlab-org/gitlab/-/blob/v14.1.0-ee/lib/gitlab/x509/signature.rb#L33), +which all must return `verified`: + +- `x509_certificate.nil?` should be false. +- `x509_certificate.revoked?` should be false. +- `verified_signature` should be true. +- `user.nil?` should be false. +- `user.verified_emails.include?(@email)` should be true. +- `certificate_email == @email` should be true. + +To investigate why a commit shows as `Unverified`: + +1. [Start a Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```shell + sudo gitlab-rails console + ``` + +1. Identify the project (either by path or ID) and full commit SHA that you're investigating. + Use this information to create `signature` to run other checks against: + + ```ruby + project = Project.find_by_full_path('group/subgroup/project') + project = Project.find_by_id('121') + commit = project.repository.commit_by(oid: '87fdbd0f9382781442053b0b76da729344e37653') + signedcommit=Gitlab::X509::Commit.new(commit) + signature=Gitlab::X509::Signature.new(signedcommit.signature_text, signedcommit.signed_text, commit.committer_email, commit.created_at) + ``` + + If you make changes to address issues identified running through the checks, restart the + Rails console and run though the checks again from the start. + +1. Check the certificate on the commit: + + ```ruby + signature.x509_certificate.nil? + signature.x509_certificate.revoked? + ``` + + Both checks should return `false`: + + ```ruby + > signature.x509_certificate.nil? + => false + > signature.x509_certificate.revoked? + => false + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/332503) causes + these checks to fail with `Validation failed: Subject key identifier is invalid`. + +1. Run a cryptographic check on the signature. The code must return `true`: + + ```ruby + signature.verified_signature + ``` + + If it returns `false` then [investigate this check further](#cryptographic-verification-checks). + +1. Confirm the email addresses match on the commit and the signature: + + - The Rails console displays the email addresses being compared. + - The final command must return `true`: + + ```ruby + sigemail=signature.__send__:certificate_email + commitemail=commit.committer_email + sigemail == commitemail + ``` + + A [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336677) exists: + only the first email in the `Subject Alternative Name` list is compared. To + display the `Subject Alternative Name` list, run: + + ```ruby + signature.__send__ :get_certificate_extension,'subjectAltName' + ``` + + If the developer's email address is not the first one in the list, this check + fails, and the commit is marked `unverified`. + +1. The email address on the commit must be associated with an account in GitLab. + This check should return `false`: + + ```ruby + signature.user.nil? + ``` + +1. Check the email address is associated with a user in GitLab. This check should + return a user, such as `#<User id:1234 @user_handle>`: + + ```ruby + User.find_by_any_email(commit.committer_email) + ``` + + If it returns `nil`, the email address is not associated with a user, and the check fails. + +1. Confirm the developer's email address is verified. This check must return true: + + ```ruby + signature.user.verified_emails.include?(commit.committer_email) + ``` + + If the previous check returned `nil`, this command displays an error: + + ```plaintext + NoMethodError (undefined method `verified_emails' for nil:NilClass) + ``` + +1. The verification status is stored in the database. To display the database record: + + ```ruby + pp X509CommitSignature.by_commit_sha(commit.sha);nil + ``` + + If all the previous checks returned the correct values: + + - `verification_status: "unverified"` indicates the database record needs + updating. [Use the Rake task](#re-verify-commits). + + - `[]` indicates the database doesn't have a record yet. Locate the commit + in GitLab to check the signature and store the result. + +#### Cryptographic verification checks + +If GitLab determines that `verified_signature` is `false`, investigate the reason +in the Rails console. These checks require `signature` to exist. Refer to the `signature` +step of the previous [main verification checks](#main-verification-checks). + +1. Check the signature, without checking the issuer, returns `true`: + + ```ruby + signature.__send__ :valid_signature? + ``` + +1. Check the signing time and date. This check must return `true`: + + ```ruby + signature.__send__ :valid_signing_time? + ``` + + - The code allows for code signing certificates to expire. + - A commit must be signed during the validity period of the certificate, + and at or after the commit's datestamp. Display the commit time and + certificate details including `not_before`, `not_after` with: + + ```ruby + commit.created_at + pp signature.__send__ :cert; nil + ``` + +1. Check the signature, including that TLS trust can be established. This check must return `true`: + + ```ruby + signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) + ``` + + 1. If this fails, add the missing certificate(s) required to establish trust + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + + 1. After adding more certificates, (if these troubleshooting steps then pass) + run the Rake task to [re-verify commits](#re-verify-commits). + + 1. Display the certificates, including in the signature: + + ```ruby + pp signature.__send__(:p7).certificates ; nil + ``` + +Ensure any additional intermediate certificate(s) and the root certificate are added +to the certificate store. For consistency with how certificate chains are built on +web servers: + +- Git clients that are signing commits should include the certificate + and all intermediate certificates in the signature. +- The GitLab certificate store should only contain the root. + +If you remove a root certificate from the GitLab +trust store, such as when it expires, commit signatures which chain back to that +root display as `unverified`. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index d46e55ca005..fa5ef35418a 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -244,8 +244,8 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" gitlab_rails['service_desk_email_mailbox_name'] = "inbox" gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_inbox_options'] = { + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { 'tenant_id': '<YOUR-TENANT-ID>', 'client_id': '<YOUR-CLIENT-ID>', 'client_secret': '<YOUR-CLIENT-SECRET>', diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 52e064ef66e..662d7e70910 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -45,6 +45,8 @@ Note the following: a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. + Additionally, the user must be an existing member of the namespace, or the user can be added as a +member of the project for contributions to be mapped. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. - For project migration imports performed over GitLab.com Groups, preserving author information is @@ -217,7 +219,7 @@ GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) ## Troubleshooting -### Import workaround for large repositories +### Import workaround for large repositories [Maximum import size limitations](#import-the-project) can prevent an import from being successful. @@ -225,7 +227,7 @@ 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. -1. Create a temporary working directory from the export: +1. Create a temporary working directory from the export: ```shell EXPORT=<filename-without-extension> @@ -238,9 +240,11 @@ reduce the repository size for another import attempt. # Prevent interference with recreating an importable file later mv project.bundle ../"$EXPORT"-original.bundle mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz + + git switch --create smaller-tmp-main ``` -1. To reduce the repository size, +1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) to reduce the number of commits. @@ -252,7 +256,7 @@ reduce the repository size for another import attempt. git gc --prune=now --aggressive # Prepare recreating an importable file - git bundle create ../project.bundle <default-branch-name> + git bundle create ../project.bundle smaller-tmp-main cd .. mv project/ ../"$EXPORT"-project cd .. @@ -268,5 +272,5 @@ reduce the repository size for another import attempt. 1. Update the imported repository's [branch protection rules](../protected_branches.md) and its [default branch](../repository/branches/default.md), and - delete the temporary, `smaller-…` branch, and + delete the temporary, `smaller-tmp-main` branch, and the local, temporary data. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 66fdace81ba..8b159a75451 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -87,59 +87,64 @@ Example `.compliance-gitlab-ci.yml` # Allows compliance team to control the ordering and interweaving of stages/jobs. # Stages without jobs defined will remain hidden. stages: -- pre-compliance -- build -- test -- pre-deploy-compliance -- deploy -- post-compliance - -variables: # can be overriden by a developer's local .gitlab-ci.yml + - pre-compliance + - build + - test + - pre-deploy-compliance + - deploy + - post-compliance + +variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml FOO: sast -sast: # none of these attributes can be overriden by a developer's local .gitlab-ci.yml +sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml variables: FOO: sast image: ruby:2.6 stage: pre-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." + - "# No after scripts." sanity check: image: ruby:2.6 stage: pre-deploy-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." - + - "# No after scripts." audit trail: image: ruby:2.6 stage: post-compliance rules: - - when: always + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success allow_failure: false before_script: - - "# No before scripts." + - "# No before scripts." script: - - echo "running $FOO" + - echo "running $FOO" after_script: - - "# No after scripts." + - "# No after scripts." -include: # Execute individual project's configuration +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. @@ -174,7 +179,7 @@ cannot change them: - Explicitly set the container image file to run the job in. This ensures that your script steps execute in the correct environment. - Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). - This ensures that your job uses the settings you intend and that they are not overriden by + This ensures that your job uses the settings you intend and that they are not overridden by project-level pipelines. ### Sharing and permissions @@ -187,33 +192,34 @@ section. You can now change the [Project visibility](../../../public_access/public_access.md). If you set **Project Visibility** to public, you can limit access to some features to **Only Project Members**. In addition, you can select the option to -[Allow users to request access](../members/index.md#prevent-users-from-requesting-access-to-a-project). +[Allow users to request access](../members/index.md#request-access-to-a-project). Use the switches to enable or disable the following features: -| Option | More access limit options | Description | -|:----------------------------------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Issues** | ✓ | Activates the GitLab issues tracker | -| **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality | -| **Pipelines** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | -| **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | -| **Analytics** | ✓ | Enables [analytics](../../analytics/) | -| **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/) | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) | -| **Operations Dashboard** | ✓ | Control access to [operations dashboard](../../../operations/index.md) +| Option | More access limit options | Description | +|:---------------------------------|:--------------------------|:--------------| +| **Issues** | ✓ | Activates the GitLab issues tracker. | +| **Repository** | ✓ | Enables [repository](../repository/) functionality | +| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | +| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | +| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | +| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | +| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images. | +| **Analytics** | ✓ | Enables [analytics](../../analytics/). | +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | +| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | +| **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). | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - - **Issue Boards** + - **issue boards** - [**Service Desk**](#service-desk) NOTE: @@ -227,7 +233,7 @@ Some features depend on others: - If you disable **Repository** functionality, GitLab also disables the following features for your project: - **Merge Requests** - - **Pipelines** + - **CI/CD** - **Container Registry** - **Git Large File Storage** - **Packages** @@ -247,7 +253,7 @@ setting **Enable CVE ID requests in the issue sidebar**. #### Disabling email notifications -Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) +Project owners can disable all [email notifications](../../profile/notifications.md) related to the project by selecting the **Disable email notifications** checkbox. ### Merge request settings @@ -350,7 +356,7 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -- You have at least the Maintainer** role in that group. +- You have at least **Maintainer** [role](../../permissions.md#project-members-permissions) in that group. - You're at least an **Owner** of the project to be transferred. - The group to which the project is being transferred to must allow creation of new projects. @@ -457,7 +463,7 @@ To do so: 1. Confirm the action by typing the project's path as instructed. NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. ## Monitor settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 643042cb96a..cae9276eafd 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -7,25 +7,30 @@ type: reference, howto # Project access tokens -NOTE: -Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). Self-managed Free instances should review their security and compliance policies with regards to [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) and consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. - > - [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. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +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: + +- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when + authenticating, you can use any non-empty value because only the token is needed. -Project access tokens are scoped to a project and can be used to authenticate with the -[GitLab API](../../../api/index.md#personalproject-access-tokens). You can also use -project access tokens with Git to authenticate over HTTPS. If you are asked for a -username when authenticating over HTTPS, you can use any non-empty value because only -the token is needed. +Project access tokens: -Project access tokens expire on the date you define, at midnight UTC. +- Expire on the date you define, at midnight UTC. +- Are supported for self-managed instances on Free tier and above. Free self-managed instances + should: + - Review their security and compliance policies with regards to + [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to + lower potential abuse. +- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).) -For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/index.md#personalproject-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). ## Creating a project access token @@ -60,10 +65,7 @@ API calls made with a project access token are associated with the corresponding These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot user cannot be added to any other project. -- 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`. - -When the project access token is [revoked](#revoking-a-project-access-token) the bot user is deleted +When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 2b901ddc17b..8902bdc21c4 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -115,7 +115,7 @@ In GitLab self-managed instances, you can limit the display of time units to hours. To do so: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Localization**. 1. Under **Time tracking**, select the **Limit display of time tracking units to hours** checkbox. diff --git a/doc/user/project/web_ide/img/open_web_ide.png b/doc/user/project/web_ide/img/open_web_ide.png Binary files differdeleted file mode 100644 index 02a5a564472..00000000000 --- a/doc/user/project/web_ide/img/open_web_ide.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 160c2314ded..010a63b7957 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -16,9 +16,22 @@ 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, -and from merge requests. - - +and from merge requests: + +- *When viewing a file, or the repository file list* - + 1. In the upper right corner of the page, select **Edit in Web IDE** if it is visible. + 1. If **Edit in Web IDE** is not visible: + 1. Select the **(angle-down)** next to **Edit** or **Gitpod**, depending on your configuration. + 1. Select **Edit in Web IDE** from the list to display it as the editing option. + 1. Select **Edit in Web IDE** to open the editor. +- *When viewing a merge request* - + 1. Go to your merge request, and select the **Overview** tab. + 1. Scroll to the widgets area, after the merge request description. + 1. Select **Edit in Web IDE** if it is visible. + 1. If **Edit in Web IDE** is not visible: + 1. Select the **(angle-down)** next to **Open in Gitpod**. + 1. Select **Open in Web IDE** from the list to display it as the editing option. + 1. Select **Open in Web IDE** to open the editor. ## File finder @@ -249,7 +262,7 @@ The image is uploaded to the same directory and is named `image.png` by default. If another file already exists with the same name, a numeric suffix is automatically added to the filename. -There are two ways to preview Markdown content in the Web IDE: +There are two ways to preview Markdown content in the Web IDE: 1. At the top of the file's tab, select **Preview Markdown** to preview the formatting in your file. You can't edit the file in this view. @@ -280,8 +293,8 @@ a `main` entry point inside the Web IDE. Live Preview is enabled for all projects on GitLab.com. If you are an administrator of a self-managed GitLab instance, and you want to enable Live Preview: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > General**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. 1. Scroll to **Web IDE** and select **Expand**:  1. Select **Enable Live Preview** and select **Save changes**. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 0507b6b78ca..d0a1f485fa8 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -46,13 +46,17 @@ for previously created wikis. ## Create the wiki home page -When a wiki is created, it is empty. On your first visit, create the landing page -users see when viewing the wiki: +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. 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. 1. Select a **Format** for styling your text. -1. Add a welcome message in the **Content** section. You can always edit it later. +1. Add a welcome message for your home page in the **Content** section. You can + always edit it later. 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one if you don't enter one yourself. 1. Select **Create page**. @@ -105,7 +109,7 @@ Wiki pages are stored as files in a Git repository, so certain characters have a ### Length restrictions for file and directory names -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. Many common file systems have a [limit of 255 bytes](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits) for file and directory names. Git and GitLab both support paths exceeding @@ -123,7 +127,7 @@ may not be able to check out the wiki locally afterward. ## Edit a wiki page -You need the [Developer role](../../permissions.md) or higher to edit a wiki page: +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. Go to the page you want to edit. @@ -138,7 +142,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need the [Maintainer role](../../permissions.md) or higher to delete a wiki page: +You need at least the [Maintainer role](../../permissions.md) to delete a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to delete. @@ -148,7 +152,7 @@ You need the [Maintainer role](../../permissions.md) or higher to delete a wiki ## Move a wiki page -You need the [Developer role](../../permissions.md) or higher to move a wiki page: +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. Go to the page you want to move. @@ -175,7 +179,7 @@ From the history page you can see: ### View changes between page versions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. +> [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: @@ -201,9 +205,9 @@ Commits to wikis are not counted in [repository analytics](../../analytics/repos ## Customize sidebar -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -You need Developer [permissions](../../permissions.md) or higher to customize the wiki +You need at least the [Developer role](../../permissions.md) to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: @@ -238,7 +242,7 @@ Administrators for self-managed GitLab installs can ## Group wikis **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab 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: @@ -306,7 +310,7 @@ to disable the wiki but toggle it on (in blue). ## Content Editor **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 77dd44e5c7f..32bb202767a 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -334,6 +334,52 @@ git config --global url."https://${user}:${personal_access_token}@gitlab.example git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" ``` +### Fetch Go modules from Geo secondary sites + +As Go modules are stored in Git repositories, you can use the [Geo](../../administration/geo/index.md) +feature that allows Git repositories to be accessed on the secondary Geo servers. + +In the following examples, the primary's site domain name is `gitlab.example.com`, +and the secondary's is `gitlab-secondary.example.com`. + +`go get` will initially generate some HTTP traffic to the primary, but when the module +download commences, the `insteadOf` configuration sends the traffic to the secondary. + +#### Use SSH to access the Geo secondary + +To fetch Go modules from the secondary using SSH: + +1. Reconfigure Git on the client to send traffic for the primary to the secondary: + + ```plaintext + git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" + ``` + +1. Ensure the client is set up for SSH access to GitLab repositories. This can be tested on the primary, + and GitLab will replicate the public key to the secondary. + +#### Use HTTP to access the Geo secondary + +Using HTTP to fetch Go modules does not work with CI/CD job tokens, only with +persistent access tokens that are replicated to the secondary. + +To fetch Go modules from the secondary using HTTP: + +1. Put in place a Git `insteadOf` redirect on the client: + + ```plaintext + git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + ``` + +1. Generate a [personal access token](../profile/personal_access_tokens.md) and + provide those credentials in the client's `~/.netrc` file: + + ```plaintext + machine gitlab.example.com login USERNAME password TOKEN + machine gitlab-secondary.example.com login USERNAME password TOKEN + ``` + ## Access project page with project ID > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. |
