diff options
Diffstat (limited to 'doc/user/project')
157 files changed, 1656 insertions, 1902 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 1834bc20aee..64a375c6a1d 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -15,7 +15,7 @@ points to. Examples for badges can be the [pipeline status](../../ci/pipelines/s [test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the project maintainers. - + ## Project badges @@ -90,6 +90,35 @@ default branch or commit SHA when the project is configured to have a private repository. This is by design, as badges are intended to be used publicly. Avoid using these placeholders if the information is sensitive. +## Use custom badge images + +Use custom badge images in a project or a group if you want to use badges other than the default +ones. + +Prerequisites: + +- A valid URL that points directly to the desired image for the badge. + If the image is located in a GitLab repository, use the raw link to the image. + +Using placeholders, here is an example badge image URL referring to a raw image at the root of a repository: + +```plaintext +https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg +``` + +To add a new badge to a group or project with a custom image: + +1. Go to your group or project and select **Settings > General**. +1. Expand **Badges**. +1. Under **Name**, enter the name for the badge. +1. Under **Link**, enter the URL that the badge should point to. +1. Under **Badge image URL**, enter the URL that points directly to the custom image that should be + displayed. +1. Select **Add badge**. + +To learn how to use custom images generated via a pipeline, see our documentation on +[accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts-by-url). + ## API You can also configure badges via the GitLab API. As in the settings, there is diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index d9e268251b7..1ecfb3b7292 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,5 +1,6 @@ --- redirect_to: 'issues/managing_issues.md' +remove_date: '2021-08-12' --- This document was moved to [another location](issues/managing_issues.md). diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index f7394093a3a..c3900d33cb8 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -91,7 +91,7 @@ Here's an example setup flow from scratch: 1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project. 1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project. -1. Install [Ingress](../../user/clusters/applications.md#ingress) as a GitLab Managed App. +1. Install [NGINX Ingress](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx) in your cluster. 1. Set up [the base domain](../../user/project/clusters/index.md#base-domain) based on the Ingress Endpoint assigned above. 1. Check if [`v2.0.0+` of `auto-deploy-image` is used in your Auto DevOps pipelines](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). @@ -116,7 +116,7 @@ or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md To use your [Deploy Board](../../user/project/deploy_boards.md): -1. Navigate to **Operations > Environments** for your project. +1. Navigate to **Deployments > Environments** for your project. 1. Set the new weight with the dropdown on the right side. 1. Confirm your selection. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index c0fb8f5848f..58bdb3d698f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -74,10 +74,10 @@ Instance profiles dynamically retrieve temporary credentials from AWS when neede To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - **Admin Area > Kubernetes**, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. +1. Click **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. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: @@ -184,13 +184,10 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After about 10 minutes, your cluster is ready to go. You can now proceed -to install some [pre-defined applications](index.md#installing-applications). +After about 10 minutes, your cluster is ready to go. NOTE: -You must add your AWS external ID to the -[IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) -to manage your cluster using `kubectl`. +If you have [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) `kubectl` and you would like to manage your cluster with it, you must add your AWS external ID in the AWS configuration. For more information on how to configure AWS CLI, see [using an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount). ### Cluster creation flow @@ -292,7 +289,7 @@ you've assigned the role the correct permissions. ### Key Pairs are not loaded -GitLab loads the key pairs from the **Cluster Region** specified. Ensure that key pair exists in that region. +GitLab loads the key pairs from the **Cluster Region** specified. Ensure that key pair exists in that region. #### `ROLLBACK_FAILED` during cluster creation diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index af3a17dc60c..9f0e5603785 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -46,10 +46,11 @@ Note the following: To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes 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 **Sign in with Google** button. @@ -70,8 +71,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster is ready. You can now proceed -to install some [pre-defined applications](index.md#installing-applications). +After a couple of minutes, your cluster is ready. ### Cloud Run for Anthos @@ -79,8 +79,8 @@ to install some [pre-defined applications](index.md#installing-applications). You can choose to use Cloud Run for Anthos in place of installing Knative and Istio separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing are enabled on the cluster at -create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. +(Knative), Istio, and HTTP Load Balancing are enabled on the cluster +from the start, and cannot be installed or uninstalled. ## Existing GKE cluster diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 1b4b4f38f4b..2ecbc4a2ff5 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding and removing Kubernetes clusters **(FREE)** +# Add a cluster using cluster certificates **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. + +WARNING: +Creating a new cluster or adding an existing cluster to GitLab through the certificate-based method +is deprecated and no longer recommended. Kubernetes cluster, similar to any other +infrastructure, should be created, updated, and 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). GitLab offers integrated cluster creation for the following Kubernetes providers: @@ -35,9 +44,9 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version 12.5 or later. This ensures the GitLab UI can be used for cluster creation. - The following GitLab access: - - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a + - [Maintainer role for a project](../../permissions.md#project-members-permissions) for a project-level cluster. - - [Maintainer access to a group](../../permissions.md#group-members-permissions) for a + - [Maintainer role for a group](../../permissions.md#group-members-permissions) for a group-level cluster. - [Admin Area access](../../admin_area/index.md) for a self-managed instance-level cluster. **(FREE SELF)** @@ -52,16 +61,10 @@ When creating a cluster in GitLab, you are asked if you would like to create eit cluster, which is the GitLab default and recommended option. - An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. -GitLab creates the necessary service accounts and privileges to install and run -[GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster, +When GitLab creates the cluster, a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace to manage the newly created cluster. -The first time you install an application into your cluster, the `tiller` service -account is created with `cluster-admin` privileges in the -`gitlab-managed-apps` namespace. This service account is used by Helm to -install and run [GitLab managed applications](index.md#installing-applications). - Helm also creates additional service accounts and other resources for each installed application. Consult the documentation of the Helm charts for each application for details. @@ -132,11 +135,8 @@ If you don't want to use a runner in privileged mode, either: - Use shared runners on GitLab.com. They don't have this security issue. - Set up your own runners using the configuration described at - [shared runners](../../gitlab_com/index.md#shared-runners). This involves: - 1. Making sure that you don't have it installed via - [the applications](index.md#installing-applications). - 1. Installing a runner - [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). + [shared runners](../../gitlab_com/index.md#shared-runners) using + [`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). ## Create new cluster @@ -144,36 +144,38 @@ New clusters can be created using GitLab on Google Kubernetes Engine (GKE) or Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. +1. Click **Integrate with a cluster certificate**. 1. Click the **Create new cluster** tab. 1. Click either **Amazon EKS** or **Google GKE**, and follow the instructions for your desired service: - [Amazon EKS](add_eks_clusters.md#new-eks-cluster). - [Google GKE](add_gke_clusters.md#creating-the-cluster-on-gke). -After creating a cluster, you can install runners for it as described in -[GitLab Managed Apps](../../clusters/applications.md). +After creating a cluster, you can [install runners](https://docs.gitlab.com/runner/install/kubernetes.html), +add a [cluster management project](../../clusters/management_project.md), +configure [Auto DevOps](../../../topics/autodevops/index.md), +or start [deploying right away](index.md#deploying-to-a-kubernetes-cluster). ## Add existing cluster If you have an existing Kubernetes cluster, you can add it to a project, group, -or instance. - -Kubernetes integration isn't supported for arm64 clusters. See the issue -[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) -for details. +or instance, and [install runners](https://docs.gitlab.com/runner/install/kubernetes.html) +on it (the cluster does not need to be added to GitLab first). -After adding an existing cluster, you can install runners for it as described in -[GitLab Managed Apps](../../clusters/applications.md). +After adding a cluster, you can add a [cluster management project](../../clusters/management_project.md), +configure [Auto DevOps](../../../topics/autodevops/index.md), +or start [deploying right away](index.md#deploying-to-a-kubernetes-cluster). ### Existing Kubernetes cluster To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - 1. Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + 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. **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. @@ -316,8 +318,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster is ready. You can now proceed -to install some [pre-defined applications](index.md#installing-applications). +After a couple of minutes, your cluster is ready. #### Disable Role-Based Access Control (RBAC) (optional) @@ -351,7 +352,8 @@ The Kubernetes cluster integration enables after you have successfully either cr a new cluster or added an existing one. To disable Kubernetes cluster integration: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click on the name of the cluster. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c2d06e0a22c..97296d22dd9 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -31,7 +31,7 @@ Besides integration at the project level, Kubernetes clusters can also be integrated at the [group level](../../group/clusters/index.md) or [GitLab instance level](../../instance/clusters/index.md). -To view your project level Kubernetes clusters, navigate to **Operations > Kubernetes** +To view your project level Kubernetes clusters, navigate to **Infrastructure > Kubernetes** from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters) and view information about your existing clusters, such as: @@ -61,6 +61,9 @@ Kubernetes version to any supported version at any time: Some GitLab features may support versions outside the range provided here. +NOTE: +[GKE Cluster creation](add_remove_clusters.md#create-new-cluster) by GitLab is currently not supported for Kubernetes 1.19+. For these versions you can create the cluster through GCP, then [Add existing cluster](add_remove_clusters.md#add-existing-cluster). See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331922) for more information. + ### Adding and removing clusters See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how @@ -169,14 +172,9 @@ for your deployment jobs to use. Otherwise, a namespace is created for you. #### Important notes -Note the following with GitLab and clusters: - -- If you [install applications](#installing-applications) on your cluster, GitLab will - create the resources required to run these even if you have chosen to manage your own - cluster. -- Be aware that manually managing resources that have been created by GitLab, like - namespaces and service accounts, can cause unexpected errors. If this occurs, try - [clearing the cluster cache](#clearing-the-cluster-cache). +Be aware that manually managing resources that have been created by GitLab, like +namespaces and service accounts, can cause unexpected errors. If this occurs, try +[clearing the cluster cache](#clearing-the-cluster-cache). #### Clearing the cluster cache @@ -189,7 +187,7 @@ your cluster. This can cause deployment jobs to fail. To clear the cache: -1. Navigate to your project's **Operations > Kubernetes** page, and select your cluster. +1. Navigate to your project's **Infrastructure > Kubernetes** page, and select your cluster. 1. Expand the **Advanced settings** section. 1. Click **Clear cluster cache**. @@ -197,19 +195,15 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. -You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -is specified as part of the Knative installation. See [Installing Applications](#installing-applications). - Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. The domain should have a wildcard DNS configured to the Ingress IP address. -After Ingress has been installed (see [Installing Applications](#installing-applications)), -you can either: +You can either: - Create an `A` record that points to the Ingress IP address with your domain provider. -- Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`. +- Enter a wildcard DNS address using a service such as `nip.io` or `xip.io`. For example, `192.168.1.1.xip.io`. To determine the external Ingress IP address, or external Ingress hostname: @@ -259,13 +253,11 @@ This list provides a generic solution, and some GitLab-specific approaches: If you see a trailing `%` on some Kubernetes versions, do not include it. -## Installing applications +## Cluster management project -GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, -Prometheus, and so on, in your project-level cluster. For more information on -installing, upgrading, uninstalling, and troubleshooting applications for -your project cluster, see -[GitLab Managed Apps](../../clusters/applications.md). +Attach a [Cluster management project](../../clusters/management_project.md) +to your cluster to manage shared resources requiring `cluster-admin` privileges for +installation, such as an Ingress controller. ## Auto DevOps @@ -351,16 +343,17 @@ You can customize the deployment namespace in a few ways: When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). -WARNING: +#### Protecting credentials + By default, anyone who can create a deployment job can access any CI/CD variable in an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. To keep your production credentials safe, consider using [protected environments](../../../ci/environments/protected_environments.md), -combined with either +combined with *one* of the following: -- a GitLab-managed cluster and namespace per environment, -- *or*, an environment-scoped cluster per protected environment. The same cluster +- A GitLab-managed cluster and namespace per environment. +- An environment-scoped cluster per protected environment. The same cluster can be added multiple times with multiple restricted service accounts. ### Integrations @@ -453,6 +446,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [the Prometheus cluster integration is enabled](../../clusters/integrations.md#prometheus-cluster-integration), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.  diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index bafb7d472c6..7a9c7eb423d 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. -GitLab makes it easy to view the logs of running pods or managed applications in +GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab in the **Log Explorer**, developers can avoid managing console tools or jumping to a different interface. The **Log Explorer** interface provides a set of filters @@ -18,10 +18,11 @@ above the log file data, depending on your configuration:  - **Namespace** - Select the environment to display. Users with Maintainer or - greater [permissions](../../permissions.md) can also select Managed Apps. -- **Search** - Only available if the Elastic Stack managed application is installed. -- **Select time range** - Select the range of time to display. Only available if the - Elastic Stack managed application is installed. + greater [permissions](../../permissions.md) can also see pods in the + `gitlab-managed-apps` namespace. +- **Search** - Only available if the [Elastic Stack integration](../../clusters/integrations.md#elastic-stack-cluster-integration) is enabled. +- **Select time range** - Select the range of time to display. + Only available if the [Elastic Stack integration](../../clusters/integrations.md#elastic-stack-cluster-integration) is enabled. - **Scroll to bottom** **{scroll_down}** - Scroll to the end of the displayed logs. - **Refresh** **{retry}** - Reload the displayed logs. @@ -43,12 +44,11 @@ a [metrics dashboard](../../../operations/metrics/index.md) and select **View lo 1. Sign in as a user with the _View pod logs_ [permissions](../../permissions.md#project-members-permissions) in the project. -1. *To navigate to the **Log Explorer** from the sidebar menu,* go to - **{cloud-gear}** **Operations > Pod 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 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. Go to **{cloud-gear}** **Operations > Environments** and find the environment + 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). @@ -81,7 +81,7 @@ Support for historical data is coming > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197879) in GitLab 12.8. -When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) +When you enable [Elastic Stack](../../clusters/integrations.md#elastic-stack-cluster-integration) on your cluster, you can filter logs displayed in the **Log Explorer** by date. Click **Show last** in the **Log Explorer** to see the available options. @@ -90,7 +90,7 @@ Click **Show last** in the **Log Explorer** to see the available options. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656) in GitLab 12.7. -When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, +When you enable [Elastic Stack](../../clusters/integrations.md#elastic-stack-cluster-integration) on your cluster, you can search the content of your logs through a search bar. The search is passed to Elasticsearch using the [simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index 102001d4f87..5e4df6009f0 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Container Host Security +# Container Host Security **(FREE)** Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can monitor and (optionally) block activity inside the containers themselves. This is done by leveraging @@ -28,8 +28,8 @@ users define profiles for these technologies. See the [installation guide](quick_start_guide.md) for the recommended steps to install the Container Host Security capabilities. This guide shows the recommended way of installing Container -Host Security through GMAv2. However, it's also possible to do a manual installation through our -Helm chart. +Host Security through the Cluster Management Project. However, it's also possible to do a manual +installation through our Helm chart. ## Features diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index fa4a5fb61d0..ebcd56078ae 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -4,11 +4,9 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Getting started with Container Host Security +# Getting started with Container Host Security **(FREE)** -The following steps are recommended for installing Container Host Security. Although you can install -some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install -applications through GMAv2 exclusively when using Container Network Security. +The following steps are recommended for installing Container Host Security. ## Installation steps @@ -21,8 +19,7 @@ The following steps are recommended to install and use Container Host Security t 1. Install and configure an Ingress node: - - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes cluster. @@ -63,19 +60,6 @@ initial troubleshooting steps that resolve the most common problems: `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. - Rerun the application project pipeline to redeploy the application. -### Using GMAv1 with GMAv2 - -When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with -applications being uninstalled or removed from the cluster. This is because GMAv2 actively -uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. -It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the -GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 -applications must be reinstalled after each run of that pipeline. This approach isn't recommended as -it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. -When using Container Network Security, the preferred and recommended path is to install all -necessary components with GMAv2 and the cluster management project. - **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) -- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) +- [Cluster Management Project](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index a7cdd73acd7..3daa48e1811 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Container Network Security +# Container Network Security **(FREE)** Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods @@ -20,8 +20,8 @@ disabled by default, as they must usually be customized to match application-spe See the [installation guide](quick_start_guide.md) for the recommended steps to install GitLab Container Network Security. This guide shows the recommended way of installing Container Network -Security through GMAv2. However, it's also possible to install Cilium manually through our Helm -chart. +Security through the Cluster Management Project. However, it's also possible to install Cilium +manually through our Helm chart. ## Features 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 bf419c69885..33aefec224a 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 @@ -4,11 +4,9 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Getting started with Container Network Security +# Getting started with Container Network Security **(FREE)** -The following steps are recommended for installing Container Network Security. Although you can -install some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install -applications through GMAv2 exclusively when using Container Network Security. +The following steps are recommended for installing Container Network Security. ## Installation steps @@ -21,8 +19,7 @@ The following steps are recommended to install and use Container Network Securit 1. Install and configure an Ingress node: - - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes cluster. @@ -60,7 +57,7 @@ use both methods simultaneously, when the application project pipeline runs the NetworkPolicy in the `auto-deploy-values.yaml` file may override policies configured in the UI editor. -## Monitoring throughput `**(ULTIMATE)**` +## Monitoring throughput **(ULTIMATE)** To view statistics for Container Network Security, you must follow the installation steps above and configure GitLab integration with Prometheus. Also, if you use custom Helm values for Cilium, you @@ -83,12 +80,8 @@ Additional information about the statistics page is available in the ## Forwarding logs to a SIEM Cilium logs can be forwarded to a SIEM or an external logging system through syslog protocol by -installing and configuring Fluentd. Fluentd can be installed through GitLab in two ways: - -- The [GMAv1 method](../../../../clusters/applications.md#fluentd) -- The [GMAv2 method](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd) - -GitLab strongly encourages using only the GMAv2 method to install Fluentd. +installing and configuring Fluentd. Fluentd can be installed through the GitLab +[Cluster Management Project](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd). ## Viewing the logs @@ -135,19 +128,6 @@ initial troubleshooting steps that resolve the most common problems: - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. - Rerun the application project pipeline to redeploy the application. -### Using GMAv1 with GMAv2 - -When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with -applications being uninstalled or removed from the cluster. This is because GMAv2 actively -uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. -It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the -GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 -applications must be reinstalled after each run of that pipeline. This approach isn't recommended as -it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. -When using Container Network Security, the preferred and recommended path is to install all -necessary components with GMAv2 and the cluster management project. - **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) -- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) +- [Cluster Management Project](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index c489a0ddd30..1314a1948d5 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Protecting your deployed applications +# Protecting your deployed applications **(FREE)** GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). These protections are available in the Kubernetes network layer and in the container itself. At @@ -18,9 +18,6 @@ containers themselves. The following capabilities are available to protect deployed applications in Kubernetes: -- Web Application Firewall - - [Overview](web_application_firewall/index.md) - - [Installation guide](web_application_firewall/quick_start_guide.md) - Container Network Security - [Overview](container_network_security/index.md) - [Installation guide](container_network_security/quick_start_guide.md) diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png Binary files differdeleted file mode 100644 index 2dd6df3d37b..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png Binary files differdeleted file mode 100644 index e88f62a2eba..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png Binary files differdeleted file mode 100644 index 1c99d4f7f96..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/protect/web_application_firewall/index.md b/doc/user/project/clusters/protect/web_application_firewall/index.md deleted file mode 100644 index 6e2e71c6ced..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -stage: Protect -group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ---- - -# Web Application Firewall - -WARNING: -The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) -in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) -in GitLab 14.0. - -A web application firewall (or WAF) filters, monitors, and blocks HTTP traffic to -and from a web application. By inspecting HTTP traffic, it can prevent attacks -stemming from web application security flaws. It can be used to detect SQL injection, -Cross-Site Scripting (XSS), Remote File Inclusion, Security Misconfigurations, and -much more. - -## Overview - -GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your -application along with a service and Ingress resource. In the GitLab [Ingress](../../../../clusters/applications.md#ingress) -deployment, the [ModSecurity](https://modsecurity.org/) -module is loaded into Ingress-NGINX by default and monitors the traffic to the applications -which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) -by default. The OWASP CRS detects and logs a wide range of common attacks. - -By default, the WAF is deployed in Detection-only mode and only logs attack attempts. - -## Requirements - -The Web Application Firewall requires: - -- **Kubernetes** - - To enable the WAF, you need: - - - Kubernetes 1.12+. - - A load balancer. You can use NGINX-Ingress by deploying it to your - Kubernetes cluster by either: - - Using the [`nginx-ingress` Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). - - Installing the [Ingress GitLab Managed App](../../../../clusters/applications.md#ingress) with WAF enabled. - -- **Configured Kubernetes objects** - - To use the WAF on an application, you need to deploy the following Kubernetes resources: - - - [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) - - [Service](https://kubernetes.io/docs/concepts/services-networking/service/) - - [Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) - -## Quick start - -If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) for -how to use the WAF with GitLab.com and a Kubernetes cluster on Google Kubernetes Engine (GKE). - -If you are using a self-managed instance of GitLab, you must configure the -[Google OAuth2 OmniAuth Provider](../../../../../integration/google.md) before -you can configure a cluster on GKE. Once this is set up, you can follow the steps on the -[quick start guide](quick_start_guide.md) -to get started. - -NOTE: -This guide shows how the WAF can be deployed using Auto DevOps. The WAF -is available by default to all applications no matter how they are deployed, -as long as they are using Ingress. - -## Network firewall vs. Web Application Firewall - -A network firewall or packet filter looks at traffic at the Network (L3) and Transport (L4) layers -of the [OSI Model](https://en.wikipedia.org/wiki/OSI_model), and denies packets from entry based on -a set of rules regarding the network in general. - -A Web Application Firewall operates at the Application (L7) layer of the OSI Model and can -examine all the packets traveling to and from a specific application. A WAF can set -more advanced rules around threat detection. - -## Features - -ModSecurity is enabled with the [OWASP Core Rule Set (CRS)](https://github.com/coreruleset/coreruleset/) by -default. The OWASP CRS logs attempts to the following attacks: - -- [SQL Injection](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection) -- [Cross-Site Scripting](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS)) -- [Local File Inclusion](https://wiki.owasp.org/index.php/Testing_for_Local_File_Inclusion) -- [Remote File Inclusion](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion) -- [Code Injection](https://wiki.owasp.org/index.php/Code_Injection) -- [Session Fixation](https://wiki.owasp.org/index.php/Session_fixation) -- [Scanner Detection](https://wiki.owasp.org/index.php/Category:Vulnerability_Scanning_Tools) -- [Metadata/Error Leakages](https://wiki.owasp.org/index.php/Improper_Error_Handling) - -It is good to have a basic knowledge of the following: - -- [Kubernetes](https://kubernetes.io/docs/home/) -- [Ingress](https://kubernetes.github.io/ingress-nginx/) -- [ModSecurity](https://www.modsecurity.org/) -- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) - -## Roadmap - -You can find more information on the product direction of the WAF in -[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/). diff --git a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md deleted file mode 100644 index e7d8d591510..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -stage: Protect -group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ---- - -# Getting started with the Web Application Firewall - -WARNING: -The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) -in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) -in GitLab 14.0. - -This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after -deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../../../../../topics/autodevops/index.md). - -The GitLab native Kubernetes integration is used, so you do not need -to create a Kubernetes cluster manually using the Google Cloud Platform console. -A simple application is created and deployed based on a GitLab template. - -These instructions also work for a self-managed GitLab instance. However, you -need to ensure your own [runners are configured](../../../../../ci/runners/README.md) and -[Google OAuth is enabled](../../../../../integration/google.md). - -The GitLab Web Application Firewall is deployed with [Ingress](../../../../clusters/applications.md#ingress), -so it is available to your applications no matter how you deploy them to Kubernetes. - -## Configuring your Google account - -Before creating and connecting your Kubernetes cluster to your GitLab project, -you need a Google Cloud Platform account. If you do not already have one, -sign up at <https://console.cloud.google.com>. You need to either sign in with an existing -Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. - -1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). -1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). - -NOTE: -Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab -Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. - -## Creating a new project from a template - -We use a GitLab project templates to get started. As the name suggests, -those projects provide a bare-bones application built on some well-known frameworks. - -1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select - **New project**. -1. Go to the **Create from template** tab where you can choose for example a Ruby on - Rails, Spring, or NodeJS Express project. - Use the Ruby on Rails template. - -  - -1. Give your project a name, optionally a description, and make it public so that - you can take advantage of the features available in the - [GitLab Ultimate plan](https://about.gitlab.com/pricing/). - -  - -1. Click **Create project**. - -Now that the project is created, the next step is to create the Kubernetes cluster -to deploy this application under. - -## Creating a Kubernetes cluster from within GitLab - -1. On the project's landing page, click **Add Kubernetes cluster** - (note that this option is also available when you navigate to **Operations > Kubernetes**). - -  - -1. On the **Create new cluster on GKE** tab, click **Sign in with Google**. - -  - -1. Connect with your Google account and click **Allow** when asked (this - appears only the first time you connect GitLab with your Google account). - -  - -1. The last step is to provide the cluster details. - 1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster. - (Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.) - 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in. - 1. Enter the number of nodes you want it to have. - 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). - -  - -1. Click **Create Kubernetes cluster**. - -After a couple of minutes, the cluster is created. You can also see its -status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). - -The next step is to install some applications on your cluster that are needed -to take full advantage of Auto DevOps. - -## Install Ingress - -The GitLab Kubernetes integration comes with some -[pre-defined applications](../../index.md#installing-applications) -for you to install. - - - -For this guide, we need to install Ingress. Ingress provides load balancing, -SSL termination, and name-based virtual hosting, using NGINX behind -the scenes. Make sure to switch the toggle to the enabled position before installing. - -Both logging and blocking modes are available for WAF. While logging mode is useful for -auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress. - - - -After Ingress is installed, wait a few seconds and copy the IP address that -is displayed in order to add in your base **Domain** at the top of the page. For -the purpose of this guide, we use the one suggested by GitLab. Once you have -filled in the domain, click **Save changes**. - - - -Prometheus should also be installed. It is an open-source monitoring and -alerting system that is used to supervise the deployed application. -Installing GitLab Runner is not required as we use the shared runners that -GitLab.com provides. - -## Enabling Auto DevOps (optional) - -Starting with GitLab 11.3, Auto DevOps is enabled by default. However, it is possible to disable -Auto DevOps at both the instance-level (for self-managed instances) and the group-level. -Follow these steps if Auto DevOps has been manually disabled: - -1. Navigate to **Settings > CI/CD > Auto DevOps**. -1. Select **Default to Auto DevOps pipeline**. -1. Select the [continuous deployment strategy](../../../../../topics/autodevops/index.md#deployment-strategy) - which automatically deploys the application to production once the pipeline - successfully runs on the `master` branch. -1. Click **Save changes**. - -  - -Once you complete all the above and save your changes, a new pipeline is -automatically created. To view the pipeline, go to **CI/CD > Pipelines**. - - - -The next section explains what each pipeline job does. - -## Deploying the application - -By now you should see the pipeline running, but what is it running exactly? - -To navigate inside the pipeline, click its status badge (its status should be "Running"). -The pipeline is split into a few stages, each running a couple of jobs. - - - -In the **build** stage, the application is built into a Docker image and then -uploaded to your project's [Container Registry](../../../../packages/container_registry/index.md) -([Auto Build](../../../../../topics/autodevops/stages.md#auto-build)). - -In the **test** stage, GitLab runs various checks on the application. - -The **production** stage is run after the tests and checks finish, and it automatically -deploys the application in Kubernetes ([Auto Deploy](../../../../../topics/autodevops/stages.md#auto-deploy)). - -The **production** stage creates Kubernetes objects -like a Deployment, Service, and Ingress resource. The -application is monitored by the WAF automatically. - -## Validating Ingress is running ModSecurity - -Now we can make sure that Ingress is running properly with ModSecurity and send -a request to ensure our application is responding correctly. You must connect to -your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). - -1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. - - This is done by running the following commands: - - ```shell - $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' - ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running - - $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;' - modsecurity on; - ``` - -1. Verify the Rails application has been installed properly. - - ```shell - $ kubectl get ns - auto-devv-2-16730183-production Active - - $ kubectl get pods -n auto-devv-2-16730183-production - NAME READY STATUS RESTARTS - production-5778cfcfcd-nqjcm 1/1 Running 0 - production-postgres-6449f8cc98-r7xgg 1/1 Running 0 - ``` - -1. To make sure the Rails application is responding, send a request to it by running: - - ```shell - $ kubectl get ing -n auto-devv-2-16730183-production - NAME HOSTS PORTS - production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 - - $ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2 - <body> - <p>You're on Rails!</p> - </body> - ``` - -Now that we have confirmed our system is properly setup, we can go ahead and test -the WAF with OWASP CRS! - -## Testing out the OWASP Core Rule Set - -Now let's send a potentially malicious request, as if we were a scanner, -checking for vulnerabilities within our application and examine the ModSecurity logs: - -```shell -$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 -<body> - <p>You're on Rails!</p> -</body> - -$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /var/log/modsec/audit.log | grep 'absinthe' -{ - "message": "Found User-Agent associated with security scanner", - "details": { - "match": "Matched \"Operator `PmFromFile' with parameter `scanners-user-agents.data' against variable `REQUEST_HEADERS:user-agent' (Value: `absinthe' )", - "reference": "o0,8v84,8t:lowercase", - "ruleId": "913100", - "file": "/etc/nginx/owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf", - "lineNumber": "33", - "data": "Matched Data: absinthe found within REQUEST_HEADERS:user-agent: absinthe", - "severity": "2", - "ver": "OWASP_CRS/3.2.0", - "rev": "", - "tags": ["application-multi", "language-multi", "platform-multi", "attack-reputation-scanner", "OWASP_CRS", "OWASP_CRS/AUTOMATION/SECURITY_SCANNER", "WASCTC/WASC-21", "OWASP_TOP_10/A7", "PCI/6.5.10"], - "maturity": "0", - "accuracy": "0" - } -} -``` - -You can see that ModSecurity logs the suspicious behavior. By sending a request -with the `User Agent: absinthe` header, which [absinthe](https://github.com/cameronhotchkies/Absinthe), -a tool for testing for SQL injections uses, we can detect that someone was -searching for vulnerabilities on our system. Detecting scanners is useful, because we -can learn if someone is trying to exploit our system. - -## Conclusion - -You can now see the benefits of a using a Web Application Firewall. -ModSecurity and the OWASP Core Rule Set, offer many more benefits. -You can explore them in more detail: - -- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/) -- [ModSecurity](https://www.modsecurity.org/) -- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) -- [AutoDevOps](../../../../../topics/autodevops/index.md) diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index e0b8c074fcf..b2054c4befb 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -63,18 +63,93 @@ 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. Add a Kubernetes cluster to your project by following the steps outlined in - [Create new cluster](../add_remove_clusters.md#create-new-cluster). - -1. Click the **Install** button next to the **Ingress** application to install Ingress. - -  - -1. After Ingress has been installed successfully, click the **Install** button next - to the **JupyterHub** application. You need the **Jupyter Hostname** provided - here in the next step. - -  +1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-oauth2-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 + #----------------------------------------------------------------------------- + # The gitlab and ingress sections must be customized! + #----------------------------------------------------------------------------- + + gitlab: + clientId: <Your OAuth Application ID> + clientSecret: <Your OAuth Application Secret> + callbackUrl: http://<Jupyter Hostname>/hub/oauth_callback, + # Limit access to members of specific projects or groups: + # allowedGitlabGroups: [ "my-group-1", "my-group-2" ] + # allowedProjectIds: [ 12345, 6789 ] + + # ingress is required for OAuth to work + ingress: + enabled: true + host: <JupyterHostname> + # tls: + # - hosts: + # - <JupyterHostanme> + # secretName: jupyter-cert + # annotations: + # kubernetes.io/ingress.class: "nginx" + # kubernetes.io/tls-acme: "true" + + #----------------------------------------------------------------------------- + # NO MODIFICATIONS REQUIRED BEYOND THIS POINT + #----------------------------------------------------------------------------- + + hub: + extraEnv: + JUPYTER_ENABLE_LAB: 1 + extraConfig: | + c.KubeSpawner.cmd = ['jupyter-labhub'] + c.GitLabOAuthenticator.scope = ['api read_repository write_repository'] + + async def add_auth_env(spawner): + ''' + We set user's id, login and access token on single user image to + enable repository integration for JupyterHub. + See: https://gitlab.com/gitlab-org/gitlab-foss/issues/47138#note_154294790 + ''' + auth_state = await spawner.user.get_auth_state() + + if not auth_state: + spawner.log.warning("No auth state for %s", spawner.user) + return + + spawner.environment['GITLAB_ACCESS_TOKEN'] = auth_state['access_token'] + spawner.environment['GITLAB_USER_LOGIN'] = auth_state['gitlab_user']['username'] + spawner.environment['GITLAB_USER_ID'] = str(auth_state['gitlab_user']['id']) + spawner.environment['GITLAB_USER_EMAIL'] = auth_state['gitlab_user']['email'] + spawner.environment['GITLAB_USER_NAME'] = auth_state['gitlab_user']['name'] + + c.KubeSpawner.pre_spawn_hook = add_auth_env + + auth: + type: gitlab + state: + enabled: true + + singleuser: + defaultUrl: "/lab" + image: + name: registry.gitlab.com/gitlab-org/jupyterhub-user-image + tag: latest + lifecycleHooks: + postStart: + exec: + command: + - "sh" + - "-c" + - > + git clone https://gitlab.com/gitlab-org/nurtch-demo.git DevOps-Runbook-Demo || true; + echo "https://oauth2:${GITLAB_ACCESS_TOKEN}@${GITLAB_HOST}" > ~/.git-credentials; + git config --global credential.helper store; + git config --global user.email "${GITLAB_USER_EMAIL}"; + git config --global user.name "${GITLAB_USER_NAME}"; + jupyter serverextension enable --py jupyterlab_git + + proxy: + service: + type: ClusterIP + ``` 1. After JupyterHub has been installed successfully, open the **Jupyter Hostname** in your browser. Click the **Sign in with GitLab** button to log in to diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index e355b562c36..e4ac1eabffe 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -15,7 +15,7 @@ Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/git Serverless architectures offer Operators and Developers the ability write highly scalable applications without provisioning a single server. -GitLab supports several ways deploy Serverless applications in both Kubernetes Environments and also major cloud FAAS environments. +GitLab supports several ways deploy Serverless applications in both Kubernetes Environments and also major cloud Function as a Service (FaaS) environments. Currently we support: @@ -35,7 +35,7 @@ of the box through its main components: For more information on Knative, visit the [Knative docs repository](https://github.com/knative/docs). -With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. +With GitLab Serverless, you can deploy both FaaS and serverless applications. ## Prerequisites @@ -53,7 +53,7 @@ To run Knative on GitLab, you need: The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner - onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. + onto the [existing Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes.html). 1. **Domain Name:** Knative provides its own load balancer using Istio, and an external IP address or hostname for all the applications served by Knative. Enter a wildcard domain to serve your applications. Configure your DNS server to use the @@ -68,54 +68,18 @@ To run Knative on GitLab, you need: `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). -1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. - See [Installing Applications](../index.md#installing-applications) for more information. +1. **Prometheus** (optional): The [Prometheus cluster integration](../../../clusters/integrations.md#prometheus-cluster-integration) + allows you to monitor the scale and traffic of your serverless function/application. 1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. See [Configuring logging](#configuring-logging) for more information. -## Installing Knative via the GitLab Kubernetes integration - -The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB -memory. **RBAC must be enabled.** - -1. [Add a Kubernetes cluster](../add_remove_clusters.md). -1. Select the **Applications** tab and scroll down to the Knative app section. Enter the domain to be used with - your application/functions (e.g. `example.com`) and click **Install**. - -  - -1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the - **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). - - NOTE: - Running `kubectl` commands on your cluster requires setting up access to the cluster first. - For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), - for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/). - -1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS - name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, - if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` - pointing the IP address or hostname of the Ingress. - -  - -You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) -on a given project, but not both. The current implementation makes use of a -`serverless.yml` file to signal a FaaS project. - -## Using an existing installation of Knative +## Configuring Knative > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless is unavailable when -adding an existing installation of Knative. - -It's also possible to use GitLab Serverless with an existing Kubernetes cluster -which already has Knative installed. You must do the following: - 1. Follow the steps to - [add an existing Kubernetes - cluster](../add_remove_clusters.md#add-existing-cluster). + [add a Kubernetes + cluster](../add_remove_clusters.md). 1. Ensure GitLab can manage Knative: - For a non-GitLab managed cluster, ensure that the service account for the token @@ -164,13 +128,17 @@ which already has Knative installed. You must do the following: kubectl apply -f knative-serving-only-role.yaml ``` - If you would rather grant permissions on a per service account basis, you can do this - using a `Role` and `RoleBinding` specific to the service account and namespace. + Alternatively, permissions can be granted on a per-service account basis + using `Role`s and `RoleBinding`s (see the [Kubernetes RBAC + documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) + for more information). 1. Follow the steps to deploy [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) onto your cluster. +1. **Optional:** For invocation metrics to show in GitLab, additional Istio metrics need to be configured in your cluster. For example, with Knative v0.9.0, you can use [this manifest](https://gitlab.com/gitlab-org/charts/knative/-/raw/v0.10.0/vendor/istio-metrics.yml). + ## Supported runtimes Serverless functions for GitLab can be run using: @@ -183,7 +151,7 @@ If a runtime is not available for the required programming language, consider de ### GitLab-managed runtimes -Currently the following GitLab-managed [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) +The following GitLab-managed [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are available: - `go` (proof of concept) @@ -352,7 +320,7 @@ 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 -under **Operations > Serverless**. +under **Infrastructure > Serverless platform**.  @@ -486,7 +454,7 @@ With all the pieces in place, the next time a CI pipeline runs the Knative appli ### Function details -Go to the **Operations > Serverless** page to see the final URL of your functions. +Go to the **Infrastructure > Serverless platform** page to see the final URL of your functions.  @@ -499,10 +467,10 @@ rows to bring up the function details page. The pod count gives you the number of pods running the serverless function instances on a given cluster. -For the Knative function invocations to appear, -[Prometheus must be installed](../index.md#installing-applications). +For the Knative function invocations to appear, the +[Prometheus cluster integration must be enabled](../../../clusters/integrations.md#prometheus-cluster-integration). -Once Prometheus is installed, a message may appear indicating that the metrics data _is +Once Prometheus is enabled, a message may appear indicating that the metrics data _is loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the @@ -611,7 +579,7 @@ or with other versions of Python. Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<project_name>-<project_id>-<environment>`) and `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate - to the **Operations > Serverless** page of your project and inspect + to the **Infrastructure > Serverless platform** page of your project and inspect the endpoint provided for your function/app.  diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 804c013d317..89c82d4dc6f 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -117,7 +117,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/  Once all of the above are set up and the pipeline has run at least once, -navigate to the environments page under **Operations > Environments**. +navigate to the environments page under **Deployments > Environments**. Deploy Boards are visible by default. You can explicitly click the triangle next to their respective environment name in order to hide them. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index a6b54474a9e..c0bc97781b6 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -28,7 +28,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is enabled on your repository. A good rule to follow is to provide access only to trusted users, -and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) +and make sure that the allowed users have the [Maintainer role or higher](../../permissions.md) in the GitLab project. If this security implication is a concern for your organization, diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index e2fa63ce519..800aa27f612 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -190,4 +190,4 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY NOTE: The special handling for the `gitlab-deploy-token` deploy token is not implemented for group deploy tokens. To make the group-level deploy token available for -CI/CD jobs, use the workaround in [issue 214014](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). +CI/CD jobs, the `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` variables should be set under **Settings** to the name and token of the group deploy token respectively. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4a2bd56b7ba..d2897c7310e 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -106,11 +106,7 @@ instance or the project's parent groups. ### Set instance-level description templates **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. -> - Enabled by default on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. You can set a description template at the **instance level** for issues and merge requests. @@ -132,11 +128,7 @@ Learn more about [instance template repository](../admin_area/settings/instance_ ### Set group-level description templates **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. -> - Enabled by default on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. With **group-level** description templates, you can store your templates in a single repository and configure the group file templates setting to point to that repository. @@ -184,7 +176,7 @@ provide `issues_template` and `merge_requests_template` attributes in the ## Description template example We use description templates for issues and merge requests in the -[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) of the +[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab) of the GitLab project, which you can refer to for some examples. NOTE: @@ -231,28 +223,3 @@ it's very hard to read otherwise.) /cc @project-manager /assign @qa-tester ``` - -## Enable or disable issue and merge request description templates at group and instance level **(PREMIUM SELF)** - -Setting issue and merge request description templates at group and instance levels -is under development but ready for production use. It is deployed behind a -feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:inherited_issuable_templates) -``` - -To enable it: - -```ruby -Feature.enable(:inherited_issuable_templates) -``` - -The feature flag affects these features: - -- Setting a templates project as issue and merge request description templates source at group level. -- Setting a templates project as issue and merge request description templates source at instance level. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 576de63d00d..eb963cb74c5 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -80,7 +80,7 @@ Check this document to learn more about [using Git LFS](../../topics/git/lfs/ind ### Configure Exclusive File Locks -You need [Maintainer permissions](../permissions.md) to configure +You need the [Maintainer role](../permissions.md) to configure Exclusive File Locks for your project through the command line. The first thing to do before using File Locking is to tell Git LFS which @@ -201,8 +201,8 @@ This process allows you to lock one file at a time through the GitLab UI and requires access to [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers. -Default branch file and directory locks only apply to the default branch set in -the project's settings (usually `master`). +Default branch file and directory locks only apply to the +[default branch](repository/branches/default.md) set in the project's settings. Changes to locked files on the default branch are blocked, including merge requests that modify locked files. Unlock the file to allow changes. @@ -226,6 +226,6 @@ who locked the file. The **Locked Files**, accessed from **Project > Repository** left menu, lists all file and directory locks. Locks can be removed by their author, or any user -with Maintainer permissions and above. +with the [Maintainer role](../permissions.md) and above. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 2e5713e10be..aa8cf4549e2 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -45,7 +45,7 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen ``` Please note that these configurations only take effect when the `.gitattributes` -file is in your default branch (usually `master`). +file is in your [default branch](repository/branches/default.md). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png Binary files differdeleted file mode 100644 index ee4ee2c6d71..00000000000 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png Binary files differdeleted file mode 100644 index 220eb207132..00000000000 --- a/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index e77932c6427..802eb3efc51 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your project from Bitbucket Cloud to GitLab +# Import your project from Bitbucket Cloud to GitLab **(FREE)** NOTE: The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 1e79107d76f..963b9f524ff 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your project from Bitbucket Server to GitLab +# Import your project from Bitbucket Server to GitLab **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 7e07ca6f865..27a84476590 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from ClearCase +# Migrating from ClearCase **(FREE)** [ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 61d4d29aa4d..55c5feff1f0 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from CVS +# Migrating from CVS **(FREE)** [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version control system similar to [SVN](svn.md). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 09505d94a8c..d3d77f16200 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your project from FogBugz to GitLab +# Import your project from FogBugz to GitLab **(FREE)** It only takes a few simple steps to import your project from FogBugz. The importer imports all your cases and comments with original case diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 5a4b16d57f5..37460da1289 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,5 +1,6 @@ --- redirect_to: 'index.md' +remove_date: '2021-08-15' --- This document was deleted. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 41141902468..9364ac4f954 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your project from Gitea to GitLab +# Import your project from Gitea to GitLab **(FREE)** Import your projects from Gitea to GitLab with minimal effort. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c8b973b673e..99b3e1acdcf 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your project from GitHub to GitLab +# Import your project from GitHub to GitLab **(FREE)** Using the importer, you can import your GitHub repositories to GitLab.com or to your self-managed GitLab instance. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 9e63b1cb617..f7eb5e43a79 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project importing from GitLab.com to your private GitLab instance +# Project importing from GitLab.com to your private GitLab instance **(FREE)** You can import your existing GitLab.com projects to your GitLab instance, but keep in mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 3728a486070..05fd04f6e48 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrate projects to a GitLab instance +# Migrate projects to a GitLab instance **(FREE)** See these documents to migrate to GitLab: diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 94eba319a17..131732d2bae 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import multiple repositories by uploading a manifest file +# Import multiple repositories by uploading a manifest file **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 8040eb07c93..f3843396b79 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from Perforce Helix +# Migrating from Perforce Helix **(FREE)** [Perforce Helix](https://www.perforce.com/) provides a set of tools which also include a centralized, proprietary version control system similar to Git. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 30a63a72cf9..6a1370f3301 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import Phabricator tasks into a GitLab project +# Import Phabricator tasks into a GitLab project **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 3ff612c51a7..e504f3678a7 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import project from repository by URL +# Import project from repository by URL **(FREE)** You can import your existing repositories by providing the Git URL: diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index e39976e00f6..b88abf91ae1 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from SVN to GitLab +# Migrating from SVN to GitLab **(FREE)** Subversion (SVN) is a central version control system (VCS) while Git is a distributed version control system. There are some major differences @@ -112,6 +112,10 @@ contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.c ## Cut over migration with svn2git +NOTE: +Any issues with svn2git should be directed to the [relevant project and maintainer](https://github.com/nirvdrum/svn2git). +Check for existing issues and history for update frequency. + If you are currently using an SVN repository, you can migrate the repository to Git and GitLab. We recommend a hard cut over - run the migration command once and then have all developers start using the new GitLab repository immediately. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 705df686fe0..910be690d0b 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Manage +group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- -# Migrate from TFVC to Git +# Migrate from TFVC to Git **(FREE)** Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes diff --git a/doc/user/project/index.md b/doc/user/project/index.md index d9283f623d4..0dcbf997452 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Projects **(FREE)** +# Organize work with projects **(FREE)** In GitLab, you can create projects to host your codebase. You can also use projects to track issues, plan work, @@ -97,7 +97,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Security Dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** - [Syntax highlighting](highlighting.md): Customize your code blocks, overriding the default language choice. -- [Badges](badges.md): Add an image to the project overview. +- [Badges](badges.md): Add an image to the **Project information** page. - [Releases](releases/index.md): Take a snapshot of the source, build output, metadata, and artifacts associated with a released version of your code. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index ef8c9d59132..ac70c7e4b4e 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -25,7 +25,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/-/profile/slack/edit) where you can select a project to enable the GitLab Slack application for.  diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md deleted file mode 100644 index 63772936fd4..00000000000 --- a/doc/user/project/integrations/hipchat.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). -<!-- This redirect file can be deleted after 2021-06-30. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index c7772ac2238..f9e15ced858 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least -[maintainer permission](../../permissions.md) on the project. +the [Maintainer role](../../permissions.md) on the project. ## Integrations diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b91a8a1fb3b..521f15f330e 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/index.md' +remove_date: '2021-07-07' --- This document was moved to [another location](../../../integration/jira/index.md). diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index b3091275835..c9ab4532760 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/jira_cloud_configuration.md' +remove_date: '2021-06-18' --- This document was moved to [another location](../../../integration/jira/jira_cloud_configuration.md). diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 485b48df01b..3aacf051c22 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/index.md' +remove_date: '2021-07-13' --- This document was moved to [another location](../../../integration/jira/index.md). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 191b8f207a1..de6eec62b96 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/jira_server_configuration.md' +remove_date: '2021-06-18' --- This document was moved to [another location](../../../integration/jira/jira_server_configuration.md). diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 20f5b73b37c..834bf15c287 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -67,9 +67,9 @@ After you enable custom slash commands in Mattermost, you need configuration information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to - GitLab as a user with [administrator permissions](../../permissions.md). -1. In the top navigation bar, go to **{admin}** **Admin Area**. -1. In the left menu, go to **Settings > Integrations** and select + GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **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** as you need it for the next step. All other values are suggestions. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 5bd4062b125..b0ae290e7cd 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -80,19 +80,6 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). -### Service templates - -[Service templates](services_templates.md) were a way to set predefined values for -a project integration across all new projects on the instance. They are deprecated and -[scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) -in GitLab 14.0. - -GitLab recommends you use [project integration management](../../admin_area/settings/project_integration_management.md) -instead of service templates. GitLab versions 13.3 and later provide -[instance-level integrations](../../admin_area/settings/project_integration_management.md#project-integration-management) -you can use. -instead. - ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. GitLab stores details of service hook requests made within the last 2 days. To view details of the requests, go to that integration's configuration page. @@ -128,6 +115,6 @@ plugins. This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. For an overview of what integrations are available, please see the -[project_services source directory](https://gitlab.com/gitlab-org/gitlab/tree/master/app/models/project_services). +[project_services source directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/models/project_services). Contributions are welcome! diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 4922c8d9b62..adc98151ce4 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -17,7 +17,7 @@ in the GitLab interface. There are two ways to set up Prometheus integration, depending on where your apps are running: -- For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). +- For deployments on Kubernetes, GitLab can be [integrated with an in-cluster Prometheus](#prometheus-cluster-integration) - For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). Once enabled, GitLab detects metrics from known services in the @@ -27,141 +27,13 @@ Once enabled, GitLab detects metrics from known services in the ## Enabling Prometheus Integration -### Managed Prometheus on Kubernetes +### Prometheus cluster integration -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. +> - [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62725) the Prometheus cluster applications in GitLab 14.0. -**Deprecated:** Managed Prometheus on Kubernetes is deprecated, and -scheduled for removal in [GitLab -14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). - -GitLab can seamlessly deploy and manage Prometheus on a -[connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. - -#### Requirements - -- A [connected Kubernetes cluster](../clusters/index.md) - -#### Getting started - -After you have a connected Kubernetes cluster, you can deploy a managed Prometheus with a single click. - -1. Go to the **Operations > Kubernetes** page to view your connected clusters -1. Select the cluster you would like to deploy Prometheus to -1. Click the **Install** button to deploy Prometheus to the cluster - - - -#### About managed Prometheus deployments - -Prometheus is deployed into the `gitlab-managed-apps` namespace, using the -[official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). -Prometheus is only accessible in the cluster, with GitLab communicating through the -[Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). - -The Prometheus server -[automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) -nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, -set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - -- `prometheus.io/scrape` to `true` to enable monitoring of the resource. -- `prometheus.io/port` to define the port of the metrics endpoint. -- `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. - -CPU and Memory consumption is monitored, but requires -[naming conventions](prometheus_library/kubernetes.md#specifying-the-environment) -to determine the environment. If you are using -[Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. - -The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed -by GitLab to clusters, is automatically annotated for monitoring providing key -response metrics: latency, throughput, and error rates. - -##### Example of Kubernetes service annotations and labels - -As an example, to activate Prometheus monitoring of a service: - -1. Add at least this annotation: `prometheus.io/scrape: 'true'`. -1. Add two labels so GitLab can retrieve metrics dynamically for any environment: - - `application: ${CI_ENVIRONMENT_SLUG}` - - `release: ${CI_ENVIRONMENT_SLUG}` -1. Create a dynamic PromQL query. For example, a query like - `temperature{application="{{ci_environment_slug}}",release="{{ci_environment_slug}}"}` to either: - - Add [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). - - Add [custom dashboards](../../../operations/metrics/dashboards/index.md). - -The following is a service definition to accomplish this: - -```yaml ---- -# Service -apiVersion: v1 -kind: Service -metadata: - name: service-${CI_PROJECT_NAME}-${CI_COMMIT_REF_SLUG} - # === Prometheus annotations === - annotations: - prometheus.io/scrape: 'true' - labels: - application: ${CI_ENVIRONMENT_SLUG} - release: ${CI_ENVIRONMENT_SLUG} - # === End of Prometheus === -spec: - selector: - app: ${CI_PROJECT_NAME} - ports: - - port: ${EXPOSED_PORT} - targetPort: ${CONTAINER_PORT} -``` - -#### Access the UI of a Prometheus managed application in Kubernetes - -You can connect directly to Prometheus, and view the Prometheus user interface, when -using a Prometheus managed application in Kubernetes: - -1. Find the name of the Prometheus pod in the user interface of your Kubernetes - provider, such as GKE, or by running the following `kubectl` command in your - terminal: - - ```shell - kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' - ``` - - The command should return a result like the following example, where - `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: - - ```plaintext - gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d - ``` - -1. Run a `kubectl port-forward` command. In the following example, `9090` is the - Prometheus server's listening port: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps - ``` - - The `port-forward` command forwards all requests sent to your system's `9090` port - to the `9090` port of the Prometheus pod. If the `9090` port on your system is used - by another application, you can change the port number before the colon to your - desired port. For example, to forward port `8080` of your local system, change the - command to: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps - ``` - -1. Open `localhost:9090` in your browser to display the Prometheus user interface. - -#### Script access to Prometheus - -You can script the access to Prometheus, extracting the name of the pod automatically like this: - -```shell -POD_INFORMATION=$(kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server') -POD_NAME=$(echo $POD_INFORMATION | awk '{print $1;}') -kubectl port-forward $POD_NAME 9090:9090 -n gitlab-managed-apps -``` +GitLab can query an in-cluster Prometheus for your metrics. +See [Prometheus cluster integration](../../clusters/integrations.md#prometheus-cluster-integration) for details. ### Manual configuration of Prometheus @@ -223,12 +95,12 @@ to integrate with. ### Precedence with multiple Prometheus configurations Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +and [cluster integration](#prometheus-cluster-integration) of Prometheus, you can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) - and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes), + and a [Prometheus cluster integration](#prometheus-cluster-integration), the manual configuration takes precedence and is used to run queries from [custom dashboards](../../../operations/metrics/dashboards/index.md) and [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index e14c1c0f6fd..1bafa4938af 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -33,7 +33,7 @@ integration services must be enabled. Prometheus needs to be deployed into the cluster and configured properly in order to gather Kubernetes metrics. GitLab supports two methods for doing so: -- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [deploy Prometheus into a connected cluster](../prometheus.md#managed-prometheus-on-kubernetes). It is automatically configured to collect Kubernetes metrics. +- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [query a Prometheus in a connected cluster](../../../clusters/integrations.md#prometheus-cluster-integration). The in-cluster Prometheus can be configured to automatically collect application metrics from your cluster. - To configure your own Prometheus server, you can follow the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). ## Specifying the Environment diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 8846aadd420..d1fe58390fe 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -27,28 +27,6 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). - -For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: - -- NGINX Ingress should be version 0.16.0 or above, with metrics enabled. -- NGINX Ingress should be annotated for Prometheus monitoring. -- Prometheus should be configured to monitor annotated pods. - -### About managed NGINX Ingress deployments - -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). - -NGINX is configured for Prometheus monitoring, by setting: - -- `enable-vts-status: "true"`, to export Prometheus metrics. -- `prometheus.io/scrape: "true"`, to enable automatic discovery. -- `prometheus.io/port: "10254"`, to specify the metrics port. - -When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. - -### Manually setting up NGINX Ingress for Prometheus monitoring - Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 4752fec976c..6bdd2c64dcf 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -27,28 +27,6 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. - -For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: - -- NGINX Ingress should be version 0.9.0 or above, with metrics enabled. -- NGINX Ingress should be annotated for Prometheus monitoring. -- Prometheus should be configured to monitor annotated pods. - -### About managed NGINX Ingress deployments - -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). - -NGINX is configured for Prometheus monitoring, by setting: - -- `enable-vts-status: "true"`, to export Prometheus metrics. -- `prometheus.io/scrape: "true"`, to enable automatic discovery. -- `prometheus.io/port: "10254"`, to specify the metrics port. - -When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. - -### Manually setting up NGINX Ingress for Prometheus monitoring - Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 93ce74eb735..37df48c75f8 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,67 +1,9 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../admin_area/settings/project_integration_management.md' +remove_date: '2021-09-09' --- -# Service templates **(FREE)** +This document was moved to [another location](../../admin_area/settings/project_integration_management.md). -WARNING: -Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) -in GitLab 14.0. Use [project integration management](#central-administration-of-project-integrations) instead. - -Using a service template, GitLab administrators can: - -- Provide default values for configuring integrations when creating new projects. -- Bulk configure all existing projects in one step. - -When you enable a service template: - -- The defaults are applied to **all** existing projects that either: - - Don't already have the integration enabled. - - Don't have custom values stored for already enabled integrations. -- Values are populated on each project's configuration page for the applicable - integration. -- Settings are stored at the project level. - -If you disable the template: - -- GitLab default values again become the default values for integrations on - new projects. -- Projects previously configured using the template continue to use those settings. - -If you change the template, the revised values are applied to new projects. This feature -does not provide central administration of integration settings. - -## Central administration of project integrations - -A new set of features is being introduced in GitLab to provide more control over -how integrations are configured at the instance, group, and project level. For -more information, read more about: - -- [Setting up project integration management](../../admin_area/settings/project_integration_management.md) (introduced in GitLab 13.3) -- [Our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). - -## Enable a service template - -Navigate to the **Admin Area > Service Templates** and choose the service -template you wish to create. - -Recommendation: - -- Test the settings on some projects individually before enabling a template. -- Copy the working settings from a project to the template. - -There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings are applied to all existing projects that do not already have -the integration configured. Fixing the integration then needs to be done project-by-project. - -## Service for external issue trackers - -The following image shows an example service template for Redmine. - - - -For each project, you still need to configure the issue tracking -URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used -by your external issue tracker. +<!-- 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/webex_teams.md b/doc/user/project/integrations/webex_teams.md index b2bf8e5731a..05515c58161 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,8 @@ 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. - - **Settings > Integrations** in the Admin Area (**{admin}**) to enable an instance-level integration. + - On the top bar, select **Menu >** **{admin}** **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. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index d74a2bec1f6..406b1e9ba6b 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -34,8 +34,10 @@ Webhooks are available: - Per project, at a project's **Settings > Webhooks** menu. **(FREE)** - Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** -NOTE: -On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. +GitLab.com enforces various [webhook limits](../../../user/gitlab_com/index.md#webhooks), including: + +- The maximum number of webhooks and their size, both per project, and per group. +- The number of webhook calls per minute. ## Possible uses for webhooks @@ -308,8 +310,10 @@ X-Gitlab-Event: Issue Hook "duplicated_to_id": null, "time_estimate": 0, "total_time_spent": 0, + "time_change": 0, "human_total_time_spent": null, "human_time_estimate": null, + "human_time_change": null, "weight": null, "iid": 23, "url": "http://example.com/diaspora/issues/23", @@ -1161,6 +1165,7 @@ X-Gitlab-Event: Pipeline Hook "id": 380987, "description": "shared-runners-manager-6.gitlab.com", "active": true, + "runner_type": "instance_type", "is_shared": true, "tags": [ "linux", @@ -1196,7 +1201,8 @@ X-Gitlab-Event: Pipeline Hook "id":380987, "description":"shared-runners-manager-6.gitlab.com", "active":true, - "is_shared":true, + "runner_type": "instance_type", + "is_shared": true, "tags": [ "linux", "docker" @@ -1230,6 +1236,7 @@ X-Gitlab-Event: Pipeline Hook "id": 380987, "description": "shared-runners-manager-6.gitlab.com", "active": true, + "runner_type": "instance_type", "is_shared": true, "tags": [ "linux", @@ -1333,6 +1340,7 @@ X-Gitlab-Event: Job Hook }, "runner": { "active": true, + "runner_type": "project_type", "is_shared": false, "id": 380987, "description": "shared-runners-manager-6.gitlab.com", diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e1b6956f873..8f71d469e34 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -34,11 +34,11 @@ boards in the same project. Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | -|------------------|--------------------------------|------------------------------|---------------------------|----------------| -| Free | Multiple | 1 | No | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | +| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | +| -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | +| Free | Multiple | 1 | No | No | +| Premium | Multiple | Multiple | Yes | Yes | +| Ultimate | Multiple | Multiple | Yes | Yes | To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. @@ -203,7 +203,7 @@ When visiting a board, issues appear ordered in any list. You're able to change that order by dragging the issues. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions. -The first time a given issue appears in any board (that is, the first time a user +The first time an issue appears in any board (that is, the first time a user loads a board containing that issue), it is ordered in relation to other issues in that list. The order is done according to [label priority](labels.md#label-priority). @@ -222,6 +222,28 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. +### GraphQL-based issue boards + +<!-- This anchor is linked from #blocked-issues as well. --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +The work-in-progress GraphQL-based boards come with these features: + +- [Edit more issue attributes](#edit-an-issue) +- [View blocked issues](#blocked-issues) + +The GraphQL-based Issue Board is a work in progress. +Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). + ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -269,40 +291,12 @@ especially in combination with [assignee lists](#assignee-lists).  -### Group issue boards **(PREMIUM)** +### Group issue boards Accessible at the group navigation level, a group issue board offers the same features as a project-level board. -It can display issues from all projects in that -group and its descendant subgroups. Similarly, you can only filter by group labels for these -boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only -group-level objects are available. - -#### GraphQL-based sidebar for group issue boards **(PREMIUM)** - -<!-- When the feature flag is removed, integrate this section into the above ("Group issue boards"). --> -<!-- This anchor is linked from #blocked-issues as well. --> - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-sidebar-for-group-issue-boards). **(PREMIUM SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -The work-in-progress GraphQL-based sidebar for group issue boards brings better performance and the -ability to edit issue titles in the issue sidebar. - -To **edit an issue's title** in the issue sidebar: - -1. In a group issue board, select the issue card. The issue sidebar opens on the right. -1. Next to the issue's title, select **Edit**. +It can display issues from all projects that fall under the group and its descendant subgroups. -This is work in progress as of GitLab 13.9. Learn more about the known issues in -[MR 51480](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51480). - -<!-- Add this at the end of the file --> +Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** @@ -318,7 +312,7 @@ assignee list: 1. Search and select the user you want to add as an assignee. Now that the assignee list is added, you can assign or unassign issues to that user -by [dragging issues](#drag-issues-between-lists) to and from an assignee list. +by [moving issues](#move-issues-and-lists) to and from an assignee list. To remove an assignee list, just as with a label list, click the trash icon.  @@ -334,7 +328,7 @@ milestone, giving you more freedom and visibility on the issue board. To add a m 1. Select the **Milestone** tab. 1. Search and click the milestone. -Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists) +Like the assignee lists, you're able to [drag issues](#move-issues-and-lists) to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. @@ -361,7 +355,7 @@ iteration. To add an iteration list: 1. In the dropdown, select an iteration. 1. Select **Add to board**. -Like the milestone lists, you're able to [drag issues](#drag-issues-between-lists) +Like the milestone lists, you're able to [drag issues](#move-issues-and-lists) to and from a iteration list to manipulate the iteration of the dragged issues.  @@ -399,7 +393,7 @@ appears on the right. There you can see and edit the issue's: - Weight - Notifications setting -You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: +You can also [drag issues](#move-issues-and-lists) to change their position and epic assignment: - To reorder an issue, drag it to the new position within a list. - To assign an issue to another epic, drag it to the epic's horizontal lane. @@ -442,27 +436,49 @@ status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. -To enable this in group issue boards, enable the [GraphQL-based sidebar](#graphql-based-sidebar-for-group-issue-boards). -The feature is enabled by default when you use group issue boards with epic swimlanes. +This feature is only supported when using the [GraphQL-based boards](#graphql-based-issue-boards). The feature is enabled by default regardless when you use group issue boards in epic swimlanes mode.  ## Actions you can take on an issue board +- [Edit an issue](#edit-an-issue). - [Create a new list](#create-a-new-list). - [Remove an existing list](#remove-a-list). - [Remove an issue from a list](#remove-an-issue-from-a-list). - [Filter issues](#filter-issues) that appear across your issue board. - [Create workflows](#create-workflows). -- [Drag issues between lists](#drag-issues-between-lists). +- [Move issues and lists](#move-issues-and-lists). - [Multi-select issue cards](#multi-select-issue-cards). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). -- Close an issue (by dragging it to the **Done** list). +- Close an issue (by dragging it to the **Closed** list). If you're not able to do some of the things above, make sure you have the right [permissions](#permissions). +### Edit an issue + +You can edit an issue without leaving the board view. +To open the right sidebar, select an issue card (not its title). + +You can edit the following issue attributes in the right sidebar: + +- Assignees +- [Epic](../group/epics/index.md) +- Milestone +- Time tracking value (view only) +- Due date +- Labels +- [Weight](issues/issue_weight.md) +- Notifications setting + +When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also edit the following issue attributes: + +- Title +- [Iteration](../group/iterations/index.md) +- Confidentiality + ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -480,12 +496,12 @@ You can now choose it to create a list. ### Remove a list Removing a list doesn't have any effect on issues and labels, as it's just the -list view that's removed. You can always restore it later if you need. +list view that's removed. You can always create it again later if you need. To remove a list from an issue board: -1. Select the **List settings** icon (**{settings}**) on the top of the list you want to remove. The - list settings sidebar opens on the right. +1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). + The list settings sidebar opens on the right. 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. @@ -516,9 +532,8 @@ The steps depend on the scope of the list: ### Filter issues -You should be able to use the filters on top of your issue board to show only -the results you want. It's similar to the filtering used in the issue tracker, -as the metadata from the issues and labels is re-used in the issue board. +You can use the filters on top of your issue board to show only +the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). You can filter by the following: @@ -532,6 +547,16 @@ You can filter by the following: - Release - Weight +#### Filtering issues in a group board + +When [filtering issues](#filter-issues) in a **group** board, keep this behavior in mind: + +- Milestones: you can filter by the milestones belonging to the group and its descendant groups. +- Labels: you can only filter by the labels belonging to the group but not its descendant groups. + +When you edit issues individually using the right sidebar, you can additionally select the +milestones and labels from the **project** that the issue is from. + ### Create workflows By reordering your lists, you can create workflows. As lists in issue boards are @@ -570,20 +595,45 @@ to another list, the label changes and a system note is recorded.  -### Drag issues between lists +### Move issues and lists + +You can move issues and lists by dragging them. + +Prerequisites: -When dragging issues between lists, different behavior occurs depending on the source list and the target list. +- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -| ------------------------------ | ------------------ | ------------ | ---------------------------- | ------------------------------------- | -| **From Open** | - | Issue closed | `B` added | `Bob` assigned | -| **From Closed** | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | -| **From label `A` list** | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | -| **From assignee `Alice` list** | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | +To move an issue, select the issue card and drag it to another position in its current list or +into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). + +To move a list, select its top bar, and drag it horizontally. +You can't move the **Open** and **Closed** lists, but you can hide them when editing an issue board. + +#### Dragging issues between lists + +To move an issue to another list, select the issue card and drag it onto that list. + +When you drag issues between lists, the result is different depending on the source list +and the target list. + +| | To Open | To Closed | To label B list | To assignee Bob list | +| ---------------------------- | -------------- | ----------- | ------------------------------ | ----------------------------- | +| **From Open** | - | Close issue | Add label B | Assign Bob | +| **From Closed** | Reopen issue | - | Reopen issue and add label B | Reopen issue and assign Bob | +| **From label A list** | Remove label A | Close issue | Remove label A and add label B | Assign Bob | +| **From assignee Alice list** | Unassign Alice | Close issue | Add label B | Unassign Alice and assign Bob | ### Multi-select issue cards -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. @@ -626,10 +676,14 @@ 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 sidebar for group issue boards **(PREMIUM SELF)** +### Enable or disable GraphQL-based issue boards **(FREE SELF)** -GraphQL-based sidebar for group issue boards is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. +NOTE: +When enabling GraphQL-based issue boards, you must also enable the +[new add list form](#enable-or-disable-new-add-list-form). + +GraphQL-based issue boards is not ready for production use. +It is deployed behind a feature flag that is **disabled by default** as of GitLab 13.12. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. @@ -685,3 +739,22 @@ To disable it: ```ruby Feature.disable(:iteration_board_lists) ``` + +### Enable or disable multi-selecting issue cards **(FREE SELF)** + +Multi-selecting issue cards is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:board_multi_select) +``` + +To disable it: + +```ruby +Feature.disable(:board_multi_select) +``` diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 25357a1db0b..ed15d7a2e63 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -77,11 +77,11 @@ least [Reporter access](../../permissions.md#project-members-permissions). Howev confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with Maintainer and Guest access sees in the -project's search results respectively. +For example, here's what a user with the [Maintainer role](../../permissions.md) and Guest access +sees in the project's search results respectively. -| Maintainer access | Guest access | -| :-----------: | :----------: | +| Maintainer role | Guest access | +|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | ## Merge Requests for Confidential Issues diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 5c95665230a..29adf396d4d 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -4,41 +4,46 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Export Issues to CSV +# Export issues to CSV **(FREE)** > Moved to GitLab Free in 12.10. -Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. +You can export issues as CSV files from GitLab, which are sent to your default +notification email address as an attachment. -## Overview +**Export Issues to CSV** enables you and your team to export all the data +collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) +file, which stores tabular data in plain text. -**Export Issues to CSV** enables you and your team to export all the data collected from issues into -a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, -which stores tabular data in plain text. +> _CSVs are a handy way of getting data from one program to another where one +program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) -> _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) +CSV files can be used with any plotter or spreadsheet-based program, such as +Microsoft Excel, Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO -->, +or Google Sheets. -CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, -Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO --> or Google Spreadsheets. +Here are some of the uses of exporting issues as CSV files: -## Use cases - -Among numerous use cases for exporting issues for CSV, we can name a few: - -- Make a snapshot of issues for offline analysis or to communicate with other teams who may not be in GitLab -- Create diagrams, graphs, and charts from the CSV data -- Present the data in any other format for auditing or sharing reasons -- Import the issues elsewhere to a system outside of GitLab -- Long-term issues' data analysis with multiple snapshots created along the time -- Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics +- Make a snapshot of issues for offline analysis or to communicate with other + teams who may not be in GitLab. +- Create diagrams, graphs, and charts from the CSV data. +- Present the data in any other format for auditing or sharing reasons. +- Import the issues elsewhere to a system outside of GitLab. +- Long-term issues' data analysis with multiple snapshots created along the + time. +- Use the long-term data to gather relevant feedback given in the issues, and + improve your product based on real metrics. ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which +issues to export using the search bar, along with the All/Open/Closed tabs. All +issues returned are exported, including those not shown on the first page.  -GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared. +GitLab asks you to confirm the number of issues and email address for the +export, after which the email is prepared.  @@ -48,33 +53,41 @@ Exported issues are always sorted by `Issue ID`. ## Format -Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: - -| Column | Description | -|---------|-------------| -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| Title | Issue `title` | -| State | `Open` or `Closed` | -| Description | Issue `description` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | +Data is encoded with a comma as the column delimiter, with `"` used to quote +fields if needed, and newlines to separate rows. The first row contains the +headers, which are listed in the following table along with a description of +the values: + +| Column | Description | +|-------------------|-------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | | Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | -| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- Issues are sent as an email attachment, with a 15 MB export limit to ensure + successful delivery across a range of email providers. If you reach the limit, + we suggest narrowing the search before export, perhaps by exporting open and + closed issues separately. +- CSV files are plain text files. This means that the exported CSV file doesn't + contain any issue attachments. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index de7a36a4886..02a4f6a4384 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Importing issues from CSV +# Importing issues from CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 2a003e68a73..e0eb35d1e49 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -48,7 +48,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. -Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. +Support for [PDF](https://gitlab.com/gitlab-org/gitlab/-/issues/32811) is planned for a future release. ## Limitations @@ -219,11 +219,14 @@ There are two ways to resolve/unresolve a Design thread:  +Resolving a discussion thread also marks any pending to-do items related to notes +inside the thread as done. This is applicable only for to-do items owned by the user triggering the action. + Note that your resolved comment pins disappear from the Design to free up space for new discussions. However, if you need to revisit or find a resolved discussion, all of your resolved threads are available in the **Resolved Comment** area at the bottom of the right sidebar. -## Add to dos for designs +## Add to-do items for designs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index a82823947dc..5b8dd617ab9 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -4,13 +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 --- -# Due dates +# Due dates **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3614) in GitLab 8.7. - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -Due dates can be used in issues to keep track of deadlines and make sure features are +Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are shipped on time. Users need at least [Reporter permissions](../../permissions.md) to be able to edit the due date. All users with permission to view the issue can view the due date. @@ -24,11 +20,11 @@ the user setting the due date.  -You can also set a due date via the issue sidebar. Expand the -sidebar and click **Edit** to pick a due date or remove the existing one. +You can also set a due date by using the issue sidebar. Expand the +sidebar and select **Edit** to pick a due date or remove the existing one. Changes are saved immediately. - + The last way to set a due date is by using [quick actions](../quick_actions.md), directly in an issue's description or comment: @@ -52,9 +48,9 @@ of the issue. Like the due date, the "day before the due date" is determined by server's timezone. Issues with due dates can also be exported as an iCalendar feed. The URL of the -feed can be added to calendar applications. The feed is accessible by clicking -on the **Subscribe to calendar** button on the following pages: +feed can be added to calendar applications. The feed is accessible by selecting +the **Subscribe to calendar** button on the following pages: -- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header -- on the **Project Issues** page -- on the **Group Issues** page +- The **Assigned Issues** page linked on the right side of the GitLab header +- The **Project Issues** page +- The **Group Issues** page diff --git a/doc/user/project/issues/img/issue_type_change_v13_12.png b/doc/user/project/issues/img/issue_type_change_v13_12.png Binary files differnew file mode 100644 index 00000000000..3b4864ffbbb --- /dev/null +++ b/doc/user/project/issues/img/issue_type_change_v13_12.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 3af6c528db9..13f5beadb16 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -221,7 +221,7 @@ merge request is also listed here. You can award emojis to issues. You can select the "thumbs up" and "thumbs down", or the gray "smiley-face" to choose from the list of available -[GitLab Flavored Markdown Emoji](../../markdown.md#emoji). +[GitLab Flavored Markdown Emoji](../../markdown.md#emojis). NOTE: Posting "+1" as a comment in a thread spams all subscribed participants of that issue, diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 9e8a75743a7..35573518626 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -315,10 +315,15 @@ issues are still displayed, but are not closed automatically.  +The automatic issue closing is also disabled in a project if the project has the issue tracker +disabled. If you want to enable automatic issue closing, make sure to +[enable GitLab Issues](../settings/index.md#sharing-and-permissions). + This only applies to issues affected by new merge requests or commits. Already -closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *in* the project and does not prevent other projects from closing it -via cross-project issues. +closed issues remain as-is. +If issue tracking is enabled, disabling automatic issue closing only applies to merge requests +attempting to automatically close issues within the same project. +Merge requests in other projects can still close another project's issues. #### Customizing the issue closing pattern **(FREE SELF)** @@ -326,9 +331,20 @@ In order to change the default issue closing pattern, GitLab administrators must [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. +## Change the issue type + +Users with [developer permission](../../permissions.md) +can change an issue's type. To do this, edit the issue and select an issue type from the +**Issue type** selector menu: + +- [Issue](index.md) +- [Incident](../../../operations/incident_management/index.md) + + + ## Deleting issues -Users with [project owner permission](../../permissions.md) can delete an issue by +Users with the [Owner role](../../permissions.md) can delete an issue by editing it and selecting **Delete issue**.  diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 0cb5b5d993e..e7adc045e98 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -282,4 +282,4 @@ To resolve the duplication, [in GitLab 13.2](https://gitlab.com/gitlab-org/gitla and later, some duplicate labels have `_duplicate<number>` appended to their titles. You can safely change these labels' titles if you prefer. -For details of the original problem, see [issue 30390](https://gitlab.com/gitlab-org/gitlab/issues/30390). +For details of the original problem, see [issue 30390](https://gitlab.com/gitlab-org/gitlab/-/issues/30390). diff --git a/doc/user/project/members/img/access_requests_management_v13_9.png b/doc/user/project/members/img/access_requests_management_v13_9.png Binary files differdeleted file mode 100644 index b7883e9d134..00000000000 --- a/doc/user/project/members/img/access_requests_management_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_accept_v13_9.png b/doc/user/project/members/img/add_user_email_accept_v13_9.png Binary files differdeleted file mode 100644 index a6b303e05ca..00000000000 --- a/doc/user/project/members/img/add_user_email_accept_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_ready_v13_8.png b/doc/user/project/members/img/add_user_email_ready_v13_8.png Binary files differdeleted file mode 100644 index a610b46a176..00000000000 --- a/doc/user/project/members/img/add_user_email_ready_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_search_v13_8.png b/doc/user/project/members/img/add_user_email_search_v13_8.png Binary files differdeleted file mode 100644 index 934cf19bd3d..00000000000 --- a/doc/user/project/members/img/add_user_email_search_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/withdraw_access_request_button.png b/doc/user/project/members/img/withdraw_access_request_button.png Binary files differdeleted file mode 100644 index e5a8fe0b356..00000000000 --- a/doc/user/project/members/img/withdraw_access_request_button.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 7dc1a9c612f..ab33ff0f6d8 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access 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 --- -# Members of a project +# Members of a project **(FREE)** Members are the users and groups who have access to your project. @@ -17,12 +17,13 @@ to perform actions. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To add a user to a project: 1. Go to your project and select **Members**. -1. On the **Invite member** tab, under **GitLab member of Email address**, type the username or email address. +1. On the **Invite member** tab, under **GitLab member or Email address**, type the username or email address. + In GitLab 13.11 and later, you can [replace this form with a modal window](#add-a-member-modal-window). 1. Select a [role](../../permissions.md). 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. 1. Select **Invite**. @@ -30,15 +31,24 @@ To add a user to a project: If the user has a GitLab account, they are added to the members list. If you used an email address, the user receives an email. +If the invitation is not accepted, GitLab sends reminder emails two, +five, and ten days later. Unaccepted invites are automatically +deleted after 90 days. + +If the user does not have a GitLab account, they are prompted to create an account +using the email address the invitation was sent to. + ## Add groups to a project -When you assign a group to a project, each user in the group gets access to the project, -based on the role they're assigned in the group. However, the user's access is also -limited by the maximum role you choose when you invite the group. +When you add a group to a project, each user in the group gets access to the project. +Each user's access is based on: + +- The role they're assigned in the group. +- The maximum role you choose when you invite the group. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To add groups to a project: @@ -61,7 +71,7 @@ retain the same permissions as the project you import them from. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To import users: @@ -74,20 +84,39 @@ A success message is displayed and the new members are now displayed in the list ## Inherited membership -When your project belongs to a group, group members inherit the membership and permission -level for the project from the group. +When your project belongs to a group, group members inherit their role +from the group.  -From the image above, we can deduce the following things: +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role from the **demo** group, + which contains the project. +- **User 1** belongs directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role from the **demo** group. + +## Remove a member from a project + +If a user is a direct member of a project, you can remove them. +If membership is inherited from a parent group, then the member can be removed only from the parent +group itself. -- There are 3 members that have access to the project. -- User0 is a Reporter and has inherited their permissions from group `demo` - which contains current project. -- User1 is shown as a **Direct member** in the **Source** column, therefore they belong directly - to the project we're inspecting. -- Administrator is the Owner and member of **all** groups and for that reason, - there is an indication of an ancestor group and inherited Owner permissions. +Prerequisite: + +- You must have the [Owner role](../../permissions.md). +- Optional. Unassign the member from all issues and merge requests that + are assigned to them. + +To remove a member from a project: + +1. Go to your project and select **Members**. +1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. +1. Select **Remove member**. ## Filter and sort members @@ -95,22 +124,21 @@ From the image above, we can deduce the following things: > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299954) in GitLab 13.10. -The following sections illustrate how you can filter and sort members in a project. To view these options, -navigate to your desired project, go to **Members**, and include the noted search terms. - -### Membership filter - -By default, inherited and direct members are displayed. The membership filter can be used to display only inherited or only direct members. +You can filter and sort members in a project. -#### Display inherited members +### Display inherited members -To display inherited members, include `Membership` `=` `Inherited` in the search text box. +1. Go to your project and select **Members**. +1. In the **Filter members** box, select `Membership` `=` `Inherited`. +1. Press Enter.  -#### Display direct members +### Display direct members -To display direct members, include `Membership` `=` `Direct` in the search text box. +1. Go to your project and select **Members**. +1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. Press Enter.  @@ -126,36 +154,41 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last  -## Invite people using their e-mail address +## Request access to a project -NOTE: -In GitLab 13.11, you can [replace this form with a modal window](#add-a-member-modal-window). +GitLab users can request to become a member of a project. -If a user you want to give access to doesn't have an account on your GitLab -instance, you can invite them just by typing their e-mail address in the -user search field. +1. Go to the project you'd like to be a member of. +1. By the project name, select **Request Access**. - + -As you can imagine, you can mix inviting multiple people and adding existing -GitLab users to the project. +An email is sent to the most recently active project maintainers. +Up to ten project maintainers are notified. +Any project maintainer can approve or decline the request. - +If a project does not have any maintainers, the notification is sent to the +most recently active owners of the project's group. + +If you change your mind before your request is approved, select +**Withdraw Access Request**. -Once done, hit **Add users to project** and watch that there is a new member -with the e-mail address we used above. From there on, you can resend the -invitation, change their access level, or even delete them. +## Prevent users from requesting access to a project - +You can prevent users from requesting access to a project. + +Prerequisite: -While unaccepted, the system automatically sends reminder emails on the second, fifth, -and tenth day after the invitation was initially sent. +- You must be the project owner. -After the user accepts the invitation, they are prompted to create a new -GitLab account using the same e-mail address the invitation was sent to. +1. Go to the project and select **Settings > General**. +1. Expand the **Visibility, project features, permissions** section. +1. Under **Project visibility**, select **Users can request access**. +1. Select **Save changes**. -NOTE: -Unaccepted invites are automatically deleted after 90 days. +## Share a project with a group + +Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). ### Add a member modal window @@ -172,10 +205,10 @@ This feature might not be available to you. Check the **version history** note a In GitLab 13.11, you can optionally replace the form to add a member with a modal window. To add a member after enabling this feature: -1. Go to your project's page. -1. In the left sidebar, go to **Members**, and then select **Invite members**. -1. Enter an email address, and select a role permission for this user. -1. (Optional) Select an **Access expiration date**. +1. Go to your project and select **Members**. +1. Select **Invite members**. +1. Enter an email address and select a role. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. ### Enable or disable modal window **(FREE SELF)** @@ -196,65 +229,3 @@ To disable it: ```ruby Feature.disable(:invite_members_group_modal) ``` - -## Project membership and requesting access - -Project owners can : - -- Allow non-members to request access to the project. -- Prevent non-members from requesting access. - -To configure this, go to the project settings and click on **Allow users to request access**. - -GitLab users can request to become a member of a project. Go to the project you'd -like to be a member of and click the **Request Access** button on the right -side of your screen. - - - -After access is requested: - -- Up to ten project maintainers are notified of the request via email. - Email is sent to the most recently active project maintainers. -- Any project maintainer can approve or decline the request on the members page. - -NOTE: -If a project does not have any maintainers, the notification is sent to the -most recently active owners of the project's group. - - - -If you change your mind before your request is approved, just click the -**Withdraw Access Request** button. - - - -## Share project with group - -Alternatively, you can [share a project with an entire group](share_project_with_groups.md) instead of adding users one by one. - -## Remove a member from the project - -Only users with permissions of [Owner](../../permissions.md#group-members-permissions) can manage -project members. - -You can remove a user from the project if the given member has a direct membership in the project. -If membership is inherited from a parent group, then the member can be removed only from the parent -group itself. - -When removing a member, you can decide whether to unassign the user from all issues and merge -requests they are currently assigned or leave the assignments as they are. - -- **Unassigning the removed member** from all issues and merge requests might be helpful when a user - is leaving a private project and you wish to revoke their access to any issues and merge requests - they are assigned. -- **Keeping the issues and merge requests assigned** might be helpful for projects that accept public - contributions where a user doesn't have to be a member to be able to contribute to issues and - merge requests. - -To remove a member from a project: - -1. Go to your project and select **Members**. -1. Next to the project member you want to remove, select **Remove member** **{remove}**. -1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. -1. Select **Remove member**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 085e4db0b94..caef5ef60b7 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -60,7 +60,7 @@ To share a project after enabling this feature: 1. Go to your project's page. 1. In the left sidebar, go to **Members**, and then select **Invite a group**. -1. Select a group, and select a **Max access level**. +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/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 09770bd447d..76aff18b00d 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Accessibility Testing +# Accessibility testing **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. @@ -17,11 +17,11 @@ impact of pending code changes. GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for measuring the accessibility of web sites, and has built a simple -[CI job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). +[CI job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. -## Accessibility Merge Request widget +## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. > - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217372) in GitLab 13.1. @@ -29,7 +29,7 @@ analyzed to a file called `accessibility`. In addition to the report artifact that is created, GitLab will also show the Accessibility Report in the merge request widget area: - + ## Configure Accessibility Testing @@ -38,7 +38,7 @@ on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](htt For GitLab 12.9 and later, to define the `a11y` job, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) included with your GitLab installation, as shown below. Add the following to your `.gitlab-ci.yml` file: @@ -67,7 +67,7 @@ For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.js NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a -link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +link to the [current template in the default branch](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) NOTE: The job definition provided by the template does not support Kubernetes yet. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5917d67c398..63d5119c1b4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -24,19 +24,17 @@ of the merge request. ## Enabling commit edits from upstream members In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), -this setting is enabled by default. It can be changed by users with Developer -permissions to the source project. Once enabled, upstream members can -retry the pipelines and jobs of the merge request: +this setting is enabled by default. It can be changed by users with the +Developer [role](../../permissions.md) for the source project. After it's enabled, +upstream members can retry the pipelines and jobs of the merge request: -1. While creating or editing a merge request, select the checkbox **Allow - commits from members who can merge to the target branch**. +1. While creating or editing a merge request, scroll to **Contribution** and + then select the **Allow commits from members who can merge to the target branch**. + checkbox. +1. Finish creating your merge request. -  - -1. Once the merge request is created, you can see that commits from members who - can merge to the target branch are allowed. - -  +After you create the merge request, the merge request widget displays a message: +**Members who can merge are allowed to add commits.** ## Pushing to the fork as the upstream member @@ -48,41 +46,39 @@ Assuming that: - The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. - The branch of the merge request is `update-docs`. -Here's how the process would look like: - -1. First, you need to get the changes that the merge request has introduced. - Click the **Check out branch** button that has some pre-populated - commands that you can run. - -  +To find and work with the changes from the fork: -1. Use the copy button to copy the first command and paste them - in your terminal: +1. Open the merge request page, and select the **Overview** tab. +1. Scroll to the merge request widget, and select **Check out branch**: +  +1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1 + to copy the `git fetch` and `git checkout` instructions to your clipboard. + Paste the commands (which look like this example) into your terminal: ```shell git fetch git@gitlab.com:thedude/awesome-project.git update-docs git checkout -b thedude-awesome-project-update-docs FETCH_HEAD ``` - This fetches the branch of the forked project and then create a local branch + These commands fetch the branch from the forked project, and create a local branch based off the fetched branch. -1. Make any changes you want and commit. -1. Push to the forked project: +1. Make your changes to the local copy of the branch, and then commit them. +1. In your terminal, push your local changes back up to the forked project. This + command pushes the local branch `thedude-awesome-project-update-docs` to the + `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository: ```shell git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs ``` - Note the colon (`:`) between the two branches. The above command pushes the - local branch `thedude-awesome-project-update-docs` to the - `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. + Note the colon (`:`) between the two branches. ## Troubleshooting ### Pipeline status unavailable from MR page of forked project -When a user forks a project, the permissions on the forked copy are not copied over +When a user forks a project, the permissions of the forked copy are not copied from the original project. The creator of the fork must grant permissions to the forked copy before members in the upstream project can view or merge the changes in the merge request. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index ac48e44da52..3c47c2af344 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -42,7 +42,7 @@ for more control of the level of oversight and security your project needs, incl - [Require security team approval.](settings.md#security-approvals-in-merge-requests) You can configure your merge request approval rules and settings through the GitLab -user interface or [with the API](../../../../api/merge_request_approvals.md). +user interface or with the [Merge request approvals API](../../../../api/merge_request_approvals.md). ## Approve a merge request @@ -97,36 +97,6 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** -## Notify external services **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. -> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -You can create an external approval rule to integrate approvals with third-party tools. -When users create, change, or close merge requests, GitLab sends a notification. -The users of the third-party tools can then approve merge requests from outside of GitLab. - -With this integration, you can integrate with third-party workflow tools, like -[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. -You can modify your external approval rules -[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). - -The lack of an external approval doesn't block the merging of a merge request. - -When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, -changes to default approval rules will **not** be applied to existing -merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) -of the rule. - -To learn more about use cases, feature discovery, and development timelines, -see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). - ## Related links - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 32f0160771f..1e4b0f659ee 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval rules +# Merge request approval rules **(FREE)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. You can define approval rules: @@ -144,7 +144,7 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) project setting. -### Code owners as eligible approvers +### Code owners as eligible approvers **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. > - Moved to GitLab Premium in 13.9. @@ -162,7 +162,7 @@ You can also [require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) for protected branches. **(PREMIUM)** -## Merge request approval segregation of duties +## Merge request approval segregation of duties **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 8769f6a7470..97e4b7da396 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval settings +# Merge request approval settings **(FREE)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index aa43d34cdd9..930df65f3fc 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -16,17 +16,17 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. -The project maintainers get Maintainer access and the regular developers get -Developer access. +The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers +get Developer access. -The maintainers mark the authoritative branches as 'Protected'. +Maintainers mark the authoritative branches as 'Protected'. -The developers push feature branches to the project and create merge requests +Developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. -By default, only users with Maintainer access can merge changes into a protected -branch. +By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a +protected branch. **Advantages** @@ -39,14 +39,14 @@ branch. ## Forking workflow -With the forking workflow the maintainers get Maintainer access and the regular +With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature branches to their own forks. -To get their changes into master they need to create a merge request across +To get their changes into the default branch, they need to create a merge request across forks. **Advantages** diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index b33919c7fbe..d11ad53a9d6 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,18 +40,18 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance). +[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. -For an example Performance job, see +For an example Browser Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget doesn't show. It must have run at least -once on the target branch (`master`, for example), before it displays in a +the Browser Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch.  @@ -70,27 +70,26 @@ using Docker-in-Docker. include: template: Verify/Browser-Performance.gitlab-ci.yml - performance: + browser_performance: variables: URL: https://example.com ``` WARNING: -In GitLab 14.0 and later, the job [is scheduled to be renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) -from `performance` to `browser_performance`. +In GitLab 13.12 and earlier, the job [was named](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) `performance`. The above example: -- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you +- Creates a `browser_performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. - Uses a template that doesn't work with Kubernetes clusters. If you are using a Kubernetes cluster, - use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) + use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) instead. - Uses a CI/CD template that is included in all GitLab installations since 12.4. If you are using GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. @@ -108,7 +107,7 @@ makes on the given URL, and change the version: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://www.sitespeed.io/ SITESPEED_VERSION: 13.2.0 @@ -127,7 +126,7 @@ if the `Total Score` metric degrades by 5 points or more: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://example.com DEGRADATION_THRESHOLD: 5 @@ -140,13 +139,13 @@ The `Total Score` metric is based on sitespeed.io's [coach performance score](ht The above CI YAML configuration is great for testing against static environments, and it can be extended for dynamic environments, but a few extra steps are required: -1. The `performance` job should run after the dynamic environment has started. +1. The `browser_performance` job should run after the dynamic environment has started. 1. In the `review` job: 1. Generate a URL list file with the dynamic URL. 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` in your job's `script`. 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) - to the `performance` job. + to the `browser_performance` job. 1. You can now run the sitespeed.io container against the desired hostname and paths. @@ -176,7 +175,7 @@ review: except: - master -performance: +browser_performance: dependencies: - review variables: @@ -191,7 +190,7 @@ GitLab version: - In 13.2 the feature was renamed from `Performance` to `Browser Performance` with additional template CI/CD variables. -- In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). +- In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: ```yaml diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index adcf4518209..e594f8048e3 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes tab in merge requests +# Changes tab in merge requests **(FREE)** The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, shows the changes to files between branches or commits. This view of changes to a @@ -70,21 +70,6 @@ merge request: This change overrides the choice you made in your user preferences and persists until you clear your browser's cookies or change this behavior again. -## Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - - - ## Incrementally expand merge request diffs By default, the diff shows only the parts of a file which are changed. @@ -106,10 +91,6 @@ specific commit page.  -NOTE: -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - ## Mark files as viewed > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. @@ -149,3 +130,42 @@ 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. +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +To avoid displaying the changes that are already on target branch in the diff, +we compare the merge request's source branch with HEAD of the target branch. + +When there are conflicts between the source and target branch, we show the +conflicts on the merge request diff as well: + + + +### Enable or disable merge request conflicts in diff **(FREE SELF)** + +Merge request conflicts in diff is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:display_merge_conflicts_in_diff) +``` + +To disable it: + +```ruby +Feature.disable(:display_merge_conflicts_in_diff) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index eaeef12444e..710638128f3 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -63,10 +63,7 @@ git cherry-pick -m 2 7a39eb0 ### Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cherry-picking-into-a-project). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0 WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -81,24 +78,10 @@ merge request is from a fork: 1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -### Enable or disable cherry-picking into a project **(FREE SELF)** +## Related links -Cherry-picking into a project is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:pick_into_project) -``` - -To disable it: - -```ruby -Feature.disable(:pick_into_project) -``` +- The [Commits API](../../../api/commits.md) enables you to add custom messages + to changes you cherry-pick through the API. <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 284d66dd591..27642a9bd5d 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,6 +1,6 @@ --- -stage: Verify -group: Testing +stage: Secure +group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -54,20 +54,25 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. +> - [Feature enhanced](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, -an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example: +the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: + + + +Previously, an indicator was displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view:  -To disable this feature, a GitLab administrator can run the following in a +To switch to the previous version of this feature, a GitLab administrator can run the following in a [Rails console](../../../administration/operations/rails_console.md): ```ruby # For the instance -Feature.disable(:codequality_mr_diff) +Feature.disable(:codequality_mr_diff_annotations) # For a single project -Feature.disable(:codequality_mr_diff, Project.find(<project id>)) +Feature.disable(:codequality_mr_diff_annotations, Project.find(<project id>)) ``` ## Use cases @@ -527,7 +532,7 @@ This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to compare to yet, so no information can be displayed. It only displays after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports have nothing to compare to. +- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md new file mode 100644 index 00000000000..1bda12468a3 --- /dev/null +++ b/doc/user/project/merge_requests/commits.md @@ -0,0 +1,28 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Commits tab in merge requests **(FREE)** + +The **Commits** tab in a merge request displays a sequential list of commits +to the Git branch your merge request is based on. From this page, you can review +full commit messages and copy a commit's SHA when you need to +[cherry-pick changes](cherry_pick_changes.md). + +## Merge requests commit navigation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To seamlessly navigate among commits in a merge request: + +1. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons below the tab buttons. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index ce1dac0a96b..430c6488b26 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -168,7 +168,8 @@ Click on **Compare branches and continue** to go to the After forking a project and applying your local changes, complete the following steps to create a merge request from your fork to contribute back to the main project: -1. Go to **Projects > Your Projects** and select your fork of the repository. +1. On the top bar, select **Menu > Project**. +1. Select **Your Projects**, then select your fork of the repository. 1. In the left menu, go to **Merge requests**, and click **New merge request**. 1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. 1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 459b8fa56ff..ce39f39f0a1 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -67,8 +67,8 @@ 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). - 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](reviews/index.md#pipeline-status-in-merge-requests-widgets). -- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps). +- Preview continuous integration [pipelines on the merge request widget](widgets.md). +- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). - Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. - Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. @@ -114,9 +114,6 @@ It is also possible to manage multiple assignees: ### Reviewer -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. - WARNING: Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and @@ -132,44 +129,7 @@ To request a review of a merge request, expand the **Reviewers** select box in the right-hand sidebar. Search for the users you want to request a review from. When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. -#### Approval Rule information for Reviewers **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. - -When editing the **Reviewers** field in a new or existing merge request, GitLab -displays the name of the matching [approval rule](approvals/rules.md) -below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. - -This example shows reviewers and approval rules when creating a new merge request: - - - -This example shows reviewers and approval rules in a merge request sidebar: - - - -#### Requesting a new review - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. - -After a reviewer completes their [merge request reviews](../../discussions/index.md), -the author of the merge request can request a new review from the reviewer: - -1. If the right sidebar in the merge request is collapsed, click the - **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. -1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) - next to the reviewer's name. - -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. +To learn more, read [Review and manage merge requests](reviews/index.md). ### Merge requests to close issues @@ -193,7 +153,7 @@ enabled by default for all new merge requests, enable it in the This option is also visible in an existing merge request next to the merge request button and can be selected or deselected before merging. -It is only visible to users with [Maintainer permissions](../../permissions.md) +It is only visible to users with the [Maintainer role](../../permissions.md) in the source project. If the user viewing the merge request does not have the correct @@ -216,18 +176,18 @@ open merge request, if the destination branch merges while the merge request is open. Merge requests are often chained in this manner, with one merge request depending on another: -- **Merge request 1**: merge `feature-alpha` into `master`. +- **Merge request 1**: merge `feature-alpha` into `main`. - **Merge request 2**: merge `feature-beta` into `feature-alpha`. These merge requests are usually handled in one of these ways: -- Merge request 1 is merged into `master` first. Merge request 2 is then - retargeted to `master`. +- Merge request 1 is merged into `main` first. Merge request 2 is then + retargeted to `main`. - Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which - now contains the contents of `feature-alpha` and `feature-beta`, is merged into `master`. + now contains the contents of `feature-alpha` and `feature-beta`, is merged into `main`. GitLab retargets up to four merge requests when their target branch is merged into -`master`, so you don't need to perform this operation manually. Merge requests from +`main`, so you don't need to perform this operation manually. Merge requests from forks are not retargeted. The feature today works only on merge. Clicking the **Remove source branch** button diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png Binary files differdeleted file mode 100644 index cc13493646d..00000000000 --- a/doc/user/project/merge_requests/img/allow_collaboration.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png Binary files differdeleted file mode 100644 index bc7678b21ec..00000000000 --- a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png Binary files differnew file mode 100644 index 00000000000..a942420d65e --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png diff --git a/doc/user/project/merge_requests/img/commit-button_v13_12.png b/doc/user/project/merge_requests/img/commit-button_v13_12.png Binary files differnew file mode 100644 index 00000000000..be154b9e60b --- /dev/null +++ b/doc/user/project/merge_requests/img/commit-button_v13_12.png diff --git a/doc/user/project/merge_requests/img/conflict_ui_v14_0.png b/doc/user/project/merge_requests/img/conflict_ui_v14_0.png Binary files differnew file mode 100644 index 00000000000..92c532351cb --- /dev/null +++ b/doc/user/project/merge_requests/img/conflict_ui_v14_0.png diff --git a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differindex ce1d6bab536..ce1d6bab536 100644 --- a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png +++ b/doc/user/project/merge_requests/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differindex 625d47b1142..625d47b1142 100644 --- a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png b/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png Binary files differnew file mode 100644 index 00000000000..65009faf426 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png b/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png Binary files differnew file mode 100644 index 00000000000..9e6d6c552e5 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png b/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png Binary files differnew file mode 100644 index 00000000000..a305f5c73f8 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png b/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png Binary files differnew file mode 100644 index 00000000000..6be64112ac6 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png b/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png Binary files differnew file mode 100644 index 00000000000..fcfe16bcd97 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f587ab34d11..b5c51c42ae9 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -17,12 +17,93 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. +To get started, read the [introduction to merge requests](getting_started.md). + +## Merge request tabs + Merge requests contain tabs at the top of the page to help you navigate to -important parts of the merge request: **Overview**, **Commits**, **Pipelines**, and **Changes**. +important parts of the merge request:  -To get started, read the [introduction to merge requests](getting_started.md). +- **Overview**: Contains the description, notifications from pipelines, and a + discussion area for [comment threads](../../discussions/index.md#resolvable-comments-and-threads) + and [code suggestions](reviews/suggestions.md). The right sidebar provides fields + to add assignees, reviewers, labels, and a milestone to your work, and the + [merge request widgets area](widgets.md) reports results from pipelines and tests. +- **Commits**: Contains a list of commits added to this merge request. For more + information, read [Commits tab in merge requests](commits.md). +- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/README.md) + pipelines and their status. +- **Changes**: Contains the diffs of files changed by this merge request. You can + [configure the display](changes.md). + +## View merge requests + +You can view merge requests for a specific project, or for all projects in a group: + +- **Specific project**: Go to your project and select **Merge requests**. +- **All projects in a group**: Go to your group and select **Merge requests**. + If your group contains subgroups, this view also displays merge requests from the subgroup projects. + GitLab displays a count of open merge requests in the left sidebar, but + [caches the value](reviews/index.md#cached-merge-request-count) for groups with a large number of + open merge requests. + +GitLab displays open merge requests, with tabs to filter the list by open and closed status: + + + +You can [search and filter](../../search/index.md#filtering-issue-and-merge-request-lists), +the results, or select a merge request to begin a review. + +## Merge request sidebar + +The **Overview** tab of a merge request displays a sidebar. In this sidebar, you +can assign, categorize, and track progress on a merge request: + +- [**Assignee**](getting_started.md#assignee): Designate the directly responsible + individual (DRI) for a merge request. With + [multiple assignees](getting_started.md#multiple-assignees), you can assign a + merge request to more than one person at a time. +- [**Reviewer**](reviews/index.md): Designate a team member to review a merge request. + Higher tiers can assign multiple reviewers, and [require approvals](approvals/index.md) + from these reviewers. +- [**Milestone**](../milestones/index.md): Track time-sensitive changes. +- [**Time tracking**](../time_tracking.md): Time spent on a merge request. +- [**Labels**](../labels.md): Categorize a merge request and display it on + appropriate [issue boards](../issue_board.md). +- **Participants**: A list of users participating or watching a merge request. +- [**Notifications**](../../profile/notifications.md): A toggle to select whether + or not to receive notifications for updates to a merge request. + +## Close a merge request + +If you decide to permanently stop work on a merge request, +GitLab recommends you close the merge request rather than +[delete it](#delete-a-merge-request). Users with +Developer, Maintainer, or Owner [roles](../../permissions.md) in a project +can close merge requests in the project: + +1. Go to the merge request you want to close. +1. Scroll to the comment box at the bottom of the page. +1. Following the comment box, select **Close merge request**. + +GitLab closes the merge request, but preserves records of the merge request, +its comments, and any associated pipelines. + +### Delete a merge request + +GitLab recommends you close, rather than delete, merge requests. + +WARNING: +You cannot undo the deletion of a merge request. + +To delete a merge request: + +1. Sign in to GitLab as a user with the project Owner [role](../../permissions.md). + Only users with this role can delete merge requests in a project. +1. Go to the merge request you want to delete, and select **Edit**. +1. Scroll to the bottom of the page, and select **Delete merge request**. ## Merge request workflows diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 865a18a6a05..d1b697add08 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -46,8 +46,8 @@ The key performance metrics that the merge request widget shows after the test c NOTE: If the Load Performance report has no data to compare, such as when you add the Load Performance job in your `.gitlab-ci.yml` for the very first time, -the Load Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Load Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch. ## Configure the Load Performance Testing job @@ -87,13 +87,13 @@ Refer to the [k6 documentation](https://k6.io/docs/) for detailed information on When your k6 test is ready, the next step is to configure the load performance testing job in GitLab CI/CD. The easiest way to do this is to use the -[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) +[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../gitlab_com/#linux-shared-runners) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/README.md#linux-shared-runners) likely have insufficient specs to handle most large k6 tests. This template runs the @@ -120,7 +120,7 @@ The above example creates a `load_performance` job in your CI/CD pipeline that r the k6 test. NOTE: -For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). +For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). k6 has [various options](https://k6.io/docs/using-k6/options) to configure how it will run tests, such as what throughput (RPS) to run with, how long the test should run, and so on. Almost all options can be configured in the test itself, but as diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 38d6ba062e4..42de04085a9 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,5 +1,6 @@ --- redirect_to: 'approvals/index.md' +remove_date: '2021-07-27' --- This document was moved to [another location](approvals/index.md). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 4534ce194bf..21282a55ff2 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -38,7 +38,7 @@ For example, given a project `mycorp/awesome-project` that imports a library at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** require changes to `awesome-lib`, and so necessitate two merge requests. Merging the `awesome-project` merge request before the `awesome-lib` one would -break the `master`branch. +break the default branch. The `awesome-project` merge request could be [marked as **Draft**](drafts.md), and the reason for the draft stated included in the comments. However, this diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index b1da336aae9..6c1e33a9ace 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -94,7 +94,7 @@ merge-request-pipeline-job: ``` You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#avoid-duplicate-pipelines) +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines) for details on avoiding two pipelines for a single merge request. ### Skipped pipelines diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 4d5d89d6508..4681ef09388 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -39,8 +39,8 @@ highlighted: After all conflicts have been marked as using 'ours' or 'theirs', the conflict can be resolved. Resolving conflicts merges the target branch of the merge request into the source branch, using the options -chosen. If the source branch is `feature` and the target branch is `master`, -this is similar to performing `git checkout feature; git merge master` locally. +chosen. If the source branch is `feature` and the target branch is `main`, +this is similar to performing `git checkout feature; git merge main` locally. ## Resolve conflicts: inline editor diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 0475996cb9b..b32dce0b230 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,5 +1,6 @@ --- redirect_to: 'reviews/index.md' +remove_date: '2021-08-03' --- This document was moved to [another location](reviews/index.md). diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png Binary files differindex c2aa0689d65..c2aa0689d65 100644 --- a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differindex 3828868965b..3828868965b 100644 --- a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e98a230c0de..317202e9303 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -7,29 +7,14 @@ type: index, reference # Review and manage merge requests **(FREE)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. + [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) -to propose changes. Your team makes [suggestions](suggestions.md) and leaves -[comments](../../../discussions/index.md). When your work is reviewed, your team -members can choose to accept or reject it. - -## View merge requests - -You can view merge requests for a specific project, or for all projects in a group: - -- **Specific project**: Go to your project and select **Merge requests**. -- **All projects in a group**: Go to your group and select **Merge requests**. - If your group contains subgroups, this view also displays merge requests from the subgroup projects. - GitLab displays a count of open merge requests in the left sidebar, but - [caches the value](#cached-merge-request-count) for groups with a large number of - open merge requests. - -GitLab displays open merge requests, with tabs to filter the list by open and closed status: - - - -You can [search and filter](../../../search/index.md#filtering-issue-and-merge-request-lists), -the results, or select a merge request to begin a review. +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. ## Bulk edit merge requests at the project level @@ -136,6 +121,45 @@ If you have a review in progress, you will be presented with the option to **Add  +### Approval Rule information for Reviewers **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. + +When editing the **Reviewers** field in a new or existing merge request, GitLab +displays the name of the matching [approval rule](../approvals/rules.md) +below the name of each suggested reviewer. [Code Owners](../../code_owners.md) are displayed as `Codeowner` without group detail. + +This example shows reviewers and approval rules when creating a new merge request: + + + +This example shows reviewers and approval rules in a merge request sidebar: + + + +### Requesting a new review + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. + +After a reviewer completes their [merge request reviews](../../../discussions/index.md), +the author of the merge request can request a new review from the reviewer: + +1. If the right sidebar in the merge request is collapsed, click the + **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. +1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) + next to the reviewer's name. + +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 @@ -180,56 +204,6 @@ Multiline comments display the comment's line numbers above the body of the comm  -## Pipeline status in merge requests widgets - -If you've set up [GitLab CI/CD](../../../../ci/README.md) in your project, -you can see: - -- Both pre-merge and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If an application is successfully deployed to an -[environment](../../../../ci/environments/index.md), the deployed environment and the link to the -Review App are both shown. - -NOTE: -When the pipeline fails in a merge request but it can still be merged, -the **Merge** button is colored red. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the [default branch](../../repository/branches/default.md) and then triggers a deployment to the staging -environment. - -Ongoing deployments are shown, and the state (deploying or deployed) -for environments. If it's the first time the branch is deployed, the link -returns a `404` error until done. During the deployment, the stop button is -disabled. If the pipeline fails to deploy, the deployment information is hidden. - - - -For more information, [read about pipelines](../../../../ci/pipelines/index.md). - -### Merge when pipeline succeeds (MWPS) - -Set a merge request that looks ready to merge to -[merge automatically when CI pipeline succeeds](../merge_when_pipeline_succeeds.md). - -### Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature branch through a merge request -on a per-branch basis. You don't need to checkout the branch, install, and preview locally. -All your changes are available to preview by anyone with the Review Apps link. - -With GitLab [Route Maps](../../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../../ci/review_apps/index.md). - ## Associated features These features are associated with merge requests: @@ -386,32 +360,7 @@ All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) ## Cached merge request count > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). - -WARNING: -This feature might not be available to you. Refer to the previous **version history** note for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327319) in GitLab 14.0. In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Enable or disable cached merge request count **(FREE SELF)** - -Cached merge request count in the left sidebar is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_merge_requests_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_merge_requests_count) -``` diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 0c8dd384b88..9409cc569a6 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -140,3 +140,7 @@ to your branch to address your reviewers' requests. WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. + +## Related links + +- [Suggestions API](../../../../api/suggestions.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 4315e5a0305..47c7e208f2d 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -7,7 +7,7 @@ type: reference, concepts # Squash and merge **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Free in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from GitLab Premium to GitLab Free in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md new file mode 100644 index 00000000000..775820870f3 --- /dev/null +++ b/doc/user/project/merge_requests/status_checks.md @@ -0,0 +1,179 @@ +--- +stage: Manage +group: Compliance +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' +--- + +# External Status Checks **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create a status check that sends merge request data to third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows +can then update the status of merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +ServiceNow, or the custom tool of your choice. The third-party tool +respond with an associated status. This status is then displayed as a non-blocking +widget within the merge request to surface this status to the merge request author or reviewers +at the merge request level itself. + +The lack of a status check response does not block the merging of a merge request. + +You can configure merge request status checks for each individual project. These are not shared between projects. + +To learn more about use cases, feature discovery, and development timelines, +see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## View the status checks on a project + +Within each project's settings, you can see a list of status checks added to the project: + +1. In your project, go to **Settings > General**. +1. Expand the **Merge requests** section. +1. Scroll down to the **Status checks** sub-section. + + + +This list shows the service name, API URL, and targeted branch. +It also provides actions to allow you to create, edit, or remove status checks. + +## Add or update a status check + +### Add a status check + +Within the **Status checks** sub-section, select the **Add status check** button. +The **Add status check** form is then shown. + + + +Filling in the form and selecting the **Add status check** button creates a new status check. + +### Update a status check + +Within the **Status checks** sub-section, select the **Edit** button +next to the status check you want to edit. +The **Update status check** form is then shown. + + + +Changing the values in the form and selecting the **Update status check** button updates the status check. + +### Form values + +For common form errors see the [troubleshooting](#troubleshooting) section below. + +#### Service name + +This name can be any alphanumerical value and **must** be set. The name **must** be unique for +the project. +The name **has** to be unique for the project. + +#### API to check + +This field requires a URL and **must** use either the HTTP or HTTPs protocols. +We **recommend** using HTTPs to protect your merge request data in transit. +The URL **must** be set and **must** be unique for the project. + +#### Target branch + +If you want to restrict the status check to a single branch, +you can use this field to set this limit. + + + +The branches list is populated from the projects [protected branches](../protected_branches.md). + +You can scroll through the list of branches or use the search box +when there are a lot of branches and the branch you are looking +for doesn't appear immediately. The search box requires +**three** alphanumeric characters to be entered for the search to begin. + +If you want the status check to be applied to **all** merge requests, +you can select the **Any branch** option. + +## Delete a status check + +Within the **Status checks** sub-section, select the **Remove...** button +next to the status check you want to delete. +The **Remove status check?** modal is then shown. + + + +To complete the deletion of the status check you must select the +**Remove status check** button. This **permanently** deletes +the status check and it **will not** be recoverable. + +## Troubleshooting + +### Duplicate value errors + +```plaintext +Name is already taken +--- +External API is already in use by another status check +``` + +On a per project basis, status checks can only use a name or API URL once. +These errors mean that either the status checks name or API URL have already +been used in this projects status checks. + +You must either choose a different +value on the current status check or update the value on the existing status check. + +### Invalid URL error + +```plaintext +Please provide a valid URL +``` + +The API to check field requires the URL provided to use either the HTTP or HTTPs protocols. +You must update the value of the field to meet this requirement. + +### Branch list error during retrieval or search + +```plaintext +Unable to fetch branches list, please close the form and try again +``` + +An unexpected response was received from the branches retrieval API. +As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although +if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. + +## Enable or disable status checks **(ULTIMATE SELF)** + +Status checks are under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:ff_compliance_approval_gates) +# For a single project +Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:ff_compliance_approval_gates) +# For a single project +Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) +``` + +## Related links + +- [External status checks API](../../../api/status_checks.md) diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 4960e9d9889..e044d50d246 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Test Coverage Visualization +# Test coverage visualization **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. @@ -65,53 +65,65 @@ to draw the visualization on the merge request expires **one week** after creati > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284822) in GitLab 13.9. -For the coverage report to properly match the files displayed on a merge request diff, the `filename` of a `class` element -must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated -Cobertura XML has the `filename` path relative to the class package directory instead. +The coverage report properly matches changed files only if the `filename` of a `class` element +contains the full path relative to the project root. However, in some coverage analysis frameworks, +the generated Cobertura XML has the `filename` path relative to the class package directory instead. -To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser attempts to build the -full path by doing the following: +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser +attempts to build the full path by: -1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. -1. Check if the candidate path exists in the project. -1. Use the first candidate that matches as the class full path. +- Extracting a portion of the `source` paths from the `sources` element and combining them with the + class `filename` path. +- Checking if the candidate path exists in the project. +- Using the first candidate that matches as the class full path. -As an example scenario, given the project's full path is `test-org/test-project`, and has the following file tree relative -to the project root: +#### Path correction example -```shell -Auth/User.cs -Lib/Utils/User.cs -src/main/java -``` +As an example, a project with: -In the Cobertura XML, the `filename` attribute in the `class` element assumes the value is a -relative path to project's root. +- A full path of `test-org/test-project`. +- The following files relative to the project root: -```xml -<class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> -``` + ```shell + Auth/User.cs + Lib/Utils/User.cs + src/main/java + ``` -And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: +In the: -```xml -<sources> - <source>/builds/test-org/test-project/Auth</source> - <source>/builds/test-org/test-project/Lib/Utils</source> -</sources> -``` +- Cobertura XML, the `filename` attribute in the `class` element assumes the value is a relative + path to the project's root: -The parser extracts `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to -the project root, combining these extracted sources and the class filename. + ```xml + <class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> + ``` -If for example there is a `class` element with the `filename` value of `User.cs`, the parser takes the first candidate path -that matches, which is `Auth/User.cs`. +- `sources` from Cobertura XML, the following paths in the format + `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: -For each `class` element, the parser attempts to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. + ```xml + <sources> + <source>/builds/test-org/test-project/Auth</source> + <source>/builds/test-org/test-project/Lib/Utils</source> + </sources> + ``` + +The parser: + +- Extracts `Auth` and `Lib/Utils` from the `sources` and uses these to determine the `class` path + relative to the project root. +- Combines these extracted `sources` and the class filename. For example, if there is a `class` + element with the `filename` value of `User.cs`, the parser takes the first candidate path that + matches, which is `Auth/User.cs`. +- For each `class` element, attempts to look for a match for each extracted `source` path up to + 100 iterations. If it reaches this limit without finding a matching path in the file tree, the + class is not included in the final coverage report. NOTE: -The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser assumes that -the `filename` of a `class` element contains the full path relative to the project root. +Automatic class path correction only works on `source` paths in the format `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. +The `source` is ignored if the path does not follow this pattern. The parser assumes that the +`filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations @@ -157,7 +169,7 @@ test-jdk11: coverage-jdk11: # Must be in a stage later than test-jdk11's stage. # The `visualize` stage does not exist by default. - # Please define it first, or chose an existing stage like `deploy`. + # Please define it first, or choose an existing stage like `deploy`. stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index cc0be389891..55e122dec76 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -6,7 +6,7 @@ type: index description: "Test your code and display reports in merge requests" --- -# Tests and reports in merge requests +# Tests and reports in merge requests **(FREE)** GitLab has the ability to test the changes included in a feature branch and display reports or link to useful information directly from merge requests: diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 676af4b2881..1d196de36e2 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In GitLab 13.9, it +by selecting **main (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the [developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md new file mode 100644 index 00000000000..92b2a8f24ef --- /dev/null +++ b/doc/user/project/merge_requests/widgets.md @@ -0,0 +1,64 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Merge request widgets **(FREE)** + +The **Overview** page of a merge request displays status updates from services +that perform actions on your merge request. All subscription levels display a +widgets area, but the content of the area depends on your subscription level +and the services you configure for your project. + +## Pipeline information + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +a [merge request](index.md) displays pipeline information in the widgets area +of the **Overview** tab: + +- Both pre-merge and post-merge pipelines, and the environment information, if any. +- Which deployments are in progress. + +If an application is successfully deployed to an +[environment](../../../ci/environments/index.md), the deployed environment and the link to the +[review app](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) are both shown. + +NOTE: +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. + +## Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging +environment. + +Ongoing deployments are shown, and the state (deploying or deployed) +for environments. If it's the first time the branch is deployed, the link +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden. + + + +For more information, [read about pipelines](../../../ci/pipelines/index.md). + +## Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). + +## Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. + +With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 4b854da116e..8b663b8edf8 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,5 +1,6 @@ --- redirect_to: 'drafts.md' +remove_date: '2021-05-19' --- This document was moved to [another location](drafts.md). diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 2399774c96d..3f7d5b6aac1 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -38,8 +38,8 @@ You can assign **group milestones** to any issue or merge request of any project To view the group milestone list, in a group, go to **{issues}** **Issues > Milestones**. You can also view all milestones you have access to in the dashboard milestones list. -To view both project milestones and group milestones you have access to, select **More > Milestones** -on the top navigation bar. +To view both project milestones and group milestones you have access to, select **Menu > Milestones** +on the top bar. For information about project and group milestones API, see: diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index f7e8d3d140c..55fde63dd47 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,5 +1,6 @@ --- redirect_to: '../../ci/README.md' +remove_date: '2021-06-01' --- This document is deprecated. See the latest [GitLab CI/CD documentation](../../ci/README.md). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index f02697a3cd5..410fdab15e7 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# DNS records overview +# DNS records overview **(FREE)** _Read this document for a brief overview of DNS records in the scope of GitLab Pages, for beginners in web development._ diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 8ed0ef82893..8c77714a2de 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Custom domains and SSL/TLS Certificates +# Custom domains and SSL/TLS certificates **(FREE)** Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. @@ -114,7 +114,7 @@ without any `/project-name`. ##### For both root and subdomains -There are a few cases where you need point both subdomain and root +There are a few cases where you need to point both the subdomain and root domain to the same website, for instance, `example.com` and `www.example.com`. They require: diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 86e34842aaf..f0a922ff390 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -6,7 +6,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages integration with Let's Encrypt +# GitLab Pages integration with Let's Encrypt **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). @@ -67,7 +67,7 @@ associated Pages domain. GitLab also renews it automatically. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30146) in GitLab 13.0. -If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, you can try obtaining the certificate again by following these steps: +If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visbility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: 1. Go to your project's **Settings > Pages**. 1. Click **Edit** on your domain. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index f79c60a933a..48412f48c12 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# SSL/TLS Certificates +# SSL/TLS certificates **(FREE)** _Read this document for a brief overview of SSL/TLS certificates in the scope of GitLab Pages, for beginners in web development._ diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 30dd337d9d8..4f2b62beab1 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create a Pages website by using a CI/CD template +# Create a Pages website by using a CI/CD template **(FREE)** GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). You can create your own `.gitlab-ci.yml` file from one of these templates, and run @@ -17,7 +17,7 @@ Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may need to do additional configuration for the Pages site to generate properly. -1. In the left sidebar, click **Project overview**. +1. On the left sidebar, select **Project information**. 1. Click **Set up CI/CD**.  diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index d9ec2aae2b7..386ed566225 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create a Pages website from a forked sample +# Create a Pages website from a forked sample **(FREE)** GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 8368b38bc80..9f80e2e7613 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create a GitLab Pages website from scratch +# Create a GitLab Pages website from scratch **(FREE)** This tutorial shows you how to create a Pages site from scratch. You start with a blank project and create your own CI file, which gives instruction to diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index 36371573fd9..f52f64626ac 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create a Pages website from a template +# Create a Pages website from a template **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. @@ -26,7 +26,6 @@ configured to generate a Pages site. and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your site. -The site can take approximately 30 minutes to deploy. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 9eb80e3287c..32826346eab 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages domain names, URLs, and base URLs +# GitLab Pages domain names, URLs, and base URLs **(FREE)** On this document, learn how to name your project for GitLab Pages according to your intended website's URL. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 2ff91292b1b..1f5e1a6ab45 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages +# GitLab Pages **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80) in GitLab Enterprise Edition 8.3. > - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173) in GitLab Enterprise Edition 8.5. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 18acb360f5a..4d6a8653657 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Exploring GitLab Pages +# Exploring GitLab Pages **(FREE)** This document is a user guide to explore the options and settings GitLab Pages offers. @@ -324,4 +324,4 @@ pages: - public ``` -The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/README.md#artifact-and-cache-settings). +The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/configure_runners.md#artifact-and-cache-settings). diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index b5932fc8766..ce49699785e 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- -# Let's Encrypt for GitLab Pages (manual process, deprecated) +# Let's Encrypt for GitLab Pages (manual process, deprecated) **(FREE)** WARNING: This method is still valid but was **deprecated** in favor of the diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 2e0fc87b3df..532a36b2327 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages Access Control +# GitLab Pages access control **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. > - Available on GitLab.com in GitLab 12.4. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 8c189614102..8ed6f214605 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create redirects for GitLab Pages +# Create redirects for GitLab Pages **(FREE)** > - [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. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 673a756f18d..4b77236f808 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -36,7 +36,7 @@ The default branch protection level is set in the [Admin Area](../admin_area/set Prerequisite: -- You must have at least maintainer permissions. +- You must have at least the [Maintainer role](../permissions.md). To protect a branch: @@ -163,7 +163,7 @@ To create a new branch through the user interface: ## Delete a protected branch From time to time, you may need to delete or clean up protected branches. -User with [Maintainer permissions](../permissions.md) and greater can manually delete protected +User with the [Maintainer role](../permissions.md) and greater can manually delete protected branches by using the GitLab web interface: 1. Go to **Repository > Branches**. @@ -179,24 +179,22 @@ command line or a Git client application. ## Allow force push on protected branches > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-allow-force-push-on-protected-branches). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. WARNING: This feature might not be available to you. Check the **version history** note above for details. -You can allow force pushes to protected branches by either setting **Allow force push** +You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to +protected branches by either setting **Allowed to force push** when you protect a new branch, or by configuring an already-protected branch. To protect a new branch and enable Force push: 1. Navigate to your project's **Settings > Repository**. 1. Expand **Protected branches**, and scroll to **Protect a branch**. -  1. Select a **Branch** or wildcard you'd like to protect. 1. Select the user levels **Allowed to merge** and **Allowed to push**. -1. To allow all users with push access to force push, toggle the **Allow force push** slider. +1. To allow all users with push access to force push, toggle the **Allowed to force push** slider. 1. To reject code pushes that change files listed in the `CODEOWNERS` file, toggle **Require approval from code owners**. 1. Click **Protect**. @@ -205,8 +203,7 @@ To enable force pushes on branches already protected: 1. Navigate to your project's **Settings > Repository**. 1. Expand **Protected branches** and scroll to **Protected branch**. -  -1. Toggle the **Allow force push** slider for the chosen branch. +1. Toggle the **Allowed to force push** slider for the chosen branch. When enabled, members who are allowed to push to this branch can also force push. @@ -226,15 +223,11 @@ To protect a new branch and enable Code Owner's approval: 1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider. 1. Click **Protect**. - - To enable Code Owner's approval to branches already protected: 1. Navigate to your project's **Settings > Repository** and expand **Protected branches**. 1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch. - - When enabled, all merge requests targeting these branches require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. @@ -249,25 +242,6 @@ run CI/CD pipelines and execute actions on jobs that are related to those branch See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. -## Enable or disable allow force push on protected branches **(FREE SELF)** - -Allow force push on protected branches is 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 enable it. - -To enable it: - -```ruby -Feature.enable(:allow_force_push_to_protected_branches) -``` - -To disable it: - -```ruby -Feature.disable(:allow_force_push_to_protected_branches) -``` - ## Changelog - **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 260f355349d..17a9cd5c8c6 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -21,7 +21,7 @@ anyone without Maintainer [permissions](../permissions.md) is prevented from cre ## Configuring protected tags -To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). +To protect a tag, you need to have at least the [Maintainer role](../permissions.md). 1. Go to the project's **Settings > Repository**. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index e1815785fb5..45cb5e74d6c 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -111,7 +111,6 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | | `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/wip` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | | `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 1ea21b1f269..71cbff9e545 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -33,7 +33,7 @@ and attach [release assets](#release-assets), like runbooks or packages. To view a list of releases: -- Go to **Project overview > Releases**, or +- On the left sidebar, select **Deployments > Releases**, or - On the project's overview page, if at least one release exists, click the number of releases. @@ -64,8 +64,7 @@ Read more about [Release permissions](../../../user/permissions.md#project-membe To create a new release through the GitLab UI: -1. Navigate to **Project overview > Releases** and click the **New release** - button. +1. On the left sidebar, select **Deployments > Releases** and select **New release**. 1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type in a new tag name. Selecting an existing tag that is already associated with a release will result in a validation error. @@ -105,7 +104,7 @@ Read more about [Release permissions](../../../user/permissions.md#project-membe To edit the details of a release: -1. Navigate to **Project overview > Releases**. +1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. 1. Click **Save changes**. @@ -151,12 +150,12 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: -1. Navigate to **Project overview > Releases**. +1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. 1. Click **Save changes**. -On the **Project overview > Releases** page, the **Milestone** is listed in the top +On the **Deployments > Releases** page, the **Milestone** is listed in the top section, along with statistics about the issues in the milestones.  @@ -176,7 +175,7 @@ You can be notified by email when a new release is created for your project. To subscribe to notifications for releases: -1. Navigate to **Project overview**. +1. On the left sidebar, select **Project information**. 1. Click **Notification setting** (the bell icon). 1. In the list, click **Custom**. 1. Select the **New release** check box. @@ -209,8 +208,8 @@ deploy_to_production: To set a deploy freeze window in the UI, complete these steps: -1. Sign in to GitLab as a user with project Maintainer [permissions](../../permissions.md). -1. Navigate to **Project overview**. +1. Sign in to GitLab as a user with the [Maintainer role](../../permissions.md). +1. On the left sidebar, select **Project information**. 1. In the left navigation menu, navigate to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Click **Expand** to see the deploy freeze table. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index deacf119d38..6c2469ac377 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -65,7 +65,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. Go to **Admin Area > Settings > Repository**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In 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**. diff --git a/doc/user/project/repository/img/download_source_code.png b/doc/user/project/repository/img/download_source_code.png Binary files differdeleted file mode 100644 index 8d62d19b291..00000000000 --- a/doc/user/project/repository/img/download_source_code.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png b/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png Binary files differdeleted file mode 100644 index 04a8f38871b..00000000000 --- a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index ed5bcc1f85a..7919850b8cc 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -8,75 +8,142 @@ type: concepts, howto # Repository **(FREE)** A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) -is what you use to store your codebase in GitLab and change it with version control. -A repository is part of a [project](../index.md), which has a lot of other features. +is where you store your code and make changes to it. Your changes are tracked with version control. + +Each [project](../index.md) contains a repository. ## Create a repository -To create a new repository, all you need to do is -[create a new project](../../../user/project/working_with_projects.md#create-a-project) or -[fork an existing project](forking_workflow.md). +To create a repository, you can: + +- [Create a project](../../../user/project/working_with_projects.md#create-a-project) or +- [Fork an existing project](forking_workflow.md). + +## Add files to a repository + +You can add files to a repository: + +- When you create a project. +- After you create a project: + - By using [the web editor](web_editor.md). + - [From the command line](../../../gitlab-basics/command-line-commands.md). + +## Commit changes to a repository + +You can [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository), +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. + In GitLab, you can add keywords to the commit + message to perform one of the following actions: + - **Trigger a GitLab CI/CD pipeline:** + If the project is configured with [GitLab CI/CD](../../../ci/README.md), + you trigger a pipeline per push, not per commit. + - **Skip pipelines:** + Add the [`ci skip`](../../../ci/yaml/README.md#skip-pipeline) keyword to + your commit message to make GitLab CI/CD skip the pipeline. + - **Cross-link issues and merge requests:** + Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages) + to keep track of related parts of your workflow. + If you mention an issue or a merge request in a commit message, they are displayed + 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) + from the UI. +- **Revert a commit:** + [Revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) + from the UI to a selected branch. +- **Sign a commit:** + Use GPG to [sign your commits](gpg_signed_commits/index.md). + +## Clone a repository + +You can [clone a repository by using the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). + +Alternatively, you can clone directly into a code editor. + +### Clone and open in Apple Xcode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. + +Projects that contain a `.xcodeproj` or `.xcworkspace` directory can be cloned +into Xcode on macOS. + +1. From the GitLab UI, go to the project's overview page. +1. Select **Clone**. +1. Select **Xcode**. + +The project is cloned onto your computer and you are +prompted to open XCode. + +### Clone and open in Visual Studio Code + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. + +All projects can be cloned into Visual Studio Code. To do that: + +1. From the GitLab UI, go to the project's overview page. +1. Click **Clone**. +1. Select **Clone with Visual Studio Code** under either HTTPS or SSH method. +1. Select a folder to clone the project into. + +When VS Code has successfully cloned your project, it opens the folder. -Once you create a new project, you can add new files via UI -(read the section below) or via command line. -To add files from the command line, follow the instructions -presented on the screen when you create a new project, or read -through them in the [command line basics](../../../gitlab-basics/start-using-git.md) -documentation. +## Download the code in a repository -> **Important:** -For security reasons, when using the command line, we strongly recommend -that you [connect with GitLab via SSH](../../../ssh/README.md). +> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. +> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. -## Files +You can download the source code that's stored in a repository. -Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), -an icon identifying the extension is shown next to the filename: +1. Above the file list, select the download icon (**{download}**). +1. From the options, select the files you want to download. - + - **Source code:** + Download the source code from the current branch you're viewing. + Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. + - **Directory:** + Download a specific directory. Visible only when you view a subdirectory. + Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. + - **Artifacts:** + Download the artifacts from the latest CI job. -### Create and edit files +## Repository languages -Host your codebase in GitLab repositories by pushing your files to GitLab. -You can either use the user interface (UI), or connect your local computer -with GitLab [through the command line](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). +For the default branch of each repository, GitLab determines which programming languages +are used. This information is displayed on the **Project information** page. -To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy -your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/index.md) -to your repository's root. + -**From the user interface:** +When new files are added, this information can take up to five minutes to update. -The GitLab UI allows you to perform lots of Git commands without having to -touch the command line. Even if you use the command line regularly, sometimes -it's easier to do so [via GitLab UI](web_editor.md): +### Add repository languages -- [Create a file](web_editor.md#create-a-file) -- [Upload a file](web_editor.md#upload-a-file) -- [File templates](web_editor.md#template-dropdowns) -- [Create a directory](web_editor.md#create-a-directory) -- [Start a merge request](web_editor.md#tips) -- [Find file history](git_history.md) -- [Identify changes by line (Git blame)](git_blame.md) +Not all files are detected and listed on the **Project information** page. Documentation, +vendor code, and most markup languages are excluded. -**From the command line:** +You can change this behavior by overriding the default settings. -To get started with the command line, please read through the -[command line basics documentation](../../../gitlab-basics/command-line-commands.md). +1. In your repository's root directory, create a file named `.gitattributes`. +1. Add a line that tells GitLab to include files of this type. For example, + to enable `.proto` files, add the following code: -### Find files + ```plaintext + *.proto linguist-detectable=true + ``` -Use the GitLab [file finder](file_finder.md) to search for files in a repository. +View a list of +[supported data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). -### Supported markup languages and extensions +This feature can use excessive CPU. +For more information, see the [troubleshooting section](#repository-languages-excessive-cpu-use). -GitLab supports a number of markup languages (sometimes called [lightweight -markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language)) -that you can use for the content of your files in a repository. They are mostly -used for documentation purposes. +### Supported markup languages -Just pick the right extension for your files and GitLab renders them -according to the markup language. +If your file has one of the following file extensions, GitLab renders the +contents of the file's [markup language](https://en.wikipedia.org/wiki/Lightweight_markup_language) in the UI. | Markup language | Extensions | | --------------- | ---------- | @@ -90,38 +157,25 @@ according to the markup language. | [creole](http://www.wikicreole.org/) | `creole` | | [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | -### Repository README and index files - -When a `README` or `index` file is present in a repository, its contents are -automatically pre-rendered by GitLab without opening it. - -They can either be plain text or have an extension of a -[supported markup language](#supported-markup-languages-and-extensions): - -Some things to note about precedence: +### README and index files -1. When both a `README` and an `index` file are present, the `README` always - takes precedence. -1. When more than one file is present with different extensions, they are - ordered alphabetically, with the exception of a file without an extension, - which is always last in precedence. For example, `README.adoc` takes - precedence over `README.md`, and `README.rst` takes precedence over - `README`. +When a `README` or `index` file is present in a repository, GitLab renders its contents. +These files can either be plain text or have the extension of a +[supported markup language](#supported-markup-languages). -### Jupyter Notebook files - -[Jupyter](https://jupyter.org/) Notebook (previously IPython Notebook) files are used for -interactive computing in many fields and contain a complete record of the -user's sessions and include code, narrative text, equations, and rich output. - -[Read how to use Jupyter notebooks with GitLab.](jupyter_notebooks/index.md) +- When both a `README` and an `index` file are present, the `README` always + takes precedence. +- When multiple files have the same name but a different extension, the files are + ordered alphabetically. Any file without an extension is ordered last. + For example, `README.adoc` takes precedence over `README.md`, and `README.rst` + takes precedence over `README`. ### OpenAPI viewer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6. -GitLab can render OpenAPI specification files with its file viewer, provided -their filenames include `openapi` or `swagger` and their extension is `yaml`, +GitLab can render OpenAPI specification files. The filename +must include `openapi` or `swagger` and the extension must be `yaml`, `yml`, or `json`. The following examples are all correct: - `openapi.yml` @@ -138,200 +192,73 @@ their filenames include `openapi` or `swagger` and their extension is `yaml`, - `openapi.gitlab.yml` - `gitlab.openapi.yml` -Then, to render them: +To render an OpenAPI file: -1. Navigate to the OpenAPI file in your repository in the GitLab UI. -1. Click the "Display OpenAPI" button which is located between the "Display source" - and "Edit" buttons (when an OpenAPI file is found, it replaces the - "Display rendered file" button). +1. Go to the OpenAPI file in your repository. +1. Between the **Display source** and **Edit** buttons, select **Display OpenAPI**. When an OpenAPI file is found, it replaces the + **Display rendered file** button. -## Branches +## Repository size -For details, see [Branches](branches/index.md). +The **Project information** page shows the size of all files in the repository. The size is +updated, at most, every 15 minutes. The file size includes repository files, artifacts, and LFS. -## Commits +The size can differ slightly from one instance to another due to compression, housekeeping, and other factors. -When you [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository), -you are introducing those changes to your branch. -Via command line, you can commit multiple times before pushing. +Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). +[GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -- **Commit message:** - A commit message is important to identity what is being changed and, - more importantly, why. In GitLab, you can add keywords to the commit - message that performs one of the actions below: - - **Trigger a GitLab CI/CD pipeline:** - If you have your project configured with [GitLab CI/CD](../../../ci/README.md), - you trigger a pipeline per push, not per commit. - - **Skip pipelines:** - You can add to your commit message the keyword - [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline), - and GitLab CI/CD skips that pipeline. - - **Cross-link issues and merge requests:** - [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages) - is great to keep track of what's is somehow related in your workflow. - If you mention an issue or a merge request in a commit message, they are shown - 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) - right from the UI. -- **Revert a commit:** - Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) - from the UI to a selected branch. -- **Sign a commit:** - Use GPG to [sign your commits](gpg_signed_commits/index.md). - -## Project and repository size +## Repository contributor graph -A project's size is reported on the project's **Details** page. The reported size is -updated every 15 minutes at most, so may not reflect recent activity. The displayed files size includes repository files, artifacts, and LFS. +All code contributors are displayed under your project's **Repository > Contributors**. -The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. - -[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by administrators. -GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). - -## Contributors - -All the contributors to your codebase are displayed under your project's **Settings > Contributors**. - -They are ordered from the collaborator with the greatest number -of commits to the fewest, and displayed on a nice graph: +The graph shows the contributor with the most commits to the fewest.  -## Repository graph - -The repository graph displays the history of the repository network visually, including branches and merges. This can help you visualize the Git flow strategy used in the repository: - - - -Find it under your project's **Repository > Graph**. +## Repository history graph -## Repository languages - -For the default branch of each repository, GitLab determines what programming languages -were used and displays this on the project's pages. If this information is missing, it's -added after updating the default branch for the project. This process can take up to five -minutes. - - - -Not all files are detected, among others; documentation, -vendored code, and most markup languages are excluded. This behavior can be -adjusted by overriding the default. For example, to enable `.proto` files to be -detected, add the following to `.gitattributes` in the root of your repository. - -```plaintext -*.proto linguist-detectable=true -``` - -Sometimes this feature can use excessive CPU. -[Read about troubleshooting this](#repository-languages-excessive-cpu-use) -and also more about customizing this feature using `.gitattributes`. - -## Locked files **(PREMIUM)** +A repository graph displays a visual history of the repository network, including branches and merges. +This graph can help you visualize the Git flow strategy used in the repository. -Use [File Locking](../file_lock.md) to -lock your files to prevent any conflicting changes. - -## Repository's API - -You can access your repositories via [repository API](../../../api/repositories.md). - -## Clone a repository - -Learn how to [clone a repository through the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). - -Alternatively, clone directly into a code editor as documented below. - -### Clone and open in Apple Xcode +Go to your project's **Repository > Graph**. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. - -Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned -into Xcode on macOS. To do that: - -1. From the GitLab UI, go to the project's overview page. -1. Click **Clone**. -1. Select **Xcode**. - -The project is cloned onto your computer in a folder of your choice and you are -prompted to open XCode. - -### Clone and open in Visual Studio Code - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. - -All projects can be cloned into Visual Studio Code. To do that: - -1. From the GitLab UI, go to the project's overview page. -1. Click **Clone**. -1. Select **VS Code**. -1. Select a folder to clone the project into. - -When VS Code has successfully cloned your project, it opens the folder. - -## Download source code - -> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. -> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. - -The source code stored in a repository can be downloaded from the UI. -By clicking the download icon, a dropdown opens with links to download the following: - - - -- **Source code:** - allows users to download the source code on branch they're currently - viewing. Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. -- **Directory:** - only shows up when viewing a sub-directory. This allows users to download - the specific directory they're currently viewing. Also available in `zip`, - `tar`, `tar.gz`, and `tar.bz2`. -- **Artifacts:** - allows users to download the artifacts of the latest CI build. - -## Redirects when changing repository paths + -When a repository path changes, it is essential to smoothly transition from the -old location to the new one. GitLab provides two kinds of redirects: the web UI -and Git push/pull redirects. +## What happens when a repository path changes -Depending on the situation, different things apply. +When a repository path changes, GitLab handles the transition from the +old location to the new one with a redirect. -When [renaming a user](../../profile/index.md#change-your-username), -[changing a group path](../../group/index.md#change-a-groups-path) or [renaming a repository](../settings/index.md#renaming-a-repository): +When you [rename a user](../../profile/index.md#change-your-username), +[change a group path](../../group/index.md#change-a-groups-path), or [rename a repository](../settings/index.md#renaming-a-repository): -- Existing web URLs for the namespace and anything under it (such as projects) will - redirect to the new URLs. -- Starting with GitLab 10.3, existing Git remote URLs for projects under the - namespace redirect to the new remote URL. Every time you push/pull to a - repository that has changed its location, a warning message to update - your remote is displayed instead of rejecting your action. - This means that any automation scripts, or Git clients continue to - work after a rename, making any transition a lot smoother. +- URLs for the namespace and everything under it, like projects, are + redirected to the new URLs. +- Git remote URLs for projects under the + namespace redirect to the new remote URL. When you push or pull to a + repository that has changed location, a warning message to update + your remote is displayed. Automation scripts or Git clients continue to + work after a rename. - The redirects are available as long as the original path is not claimed by - another group, user or project. + another group, user, or project. ## Troubleshooting ### Repository Languages: excessive CPU use -GitLab uses a Ruby gem to scan all the files in the repository to determine what languages are used. -[Sometimes this can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565) if -a file type needs to be parsed by the gem to determine what sort of file it is. +To determine which languages are in a repository's files, GitLab uses a Ruby gem. +When the gem parses a file to determine which type it is, [the process can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565). The gem contains a [heuristics configuration file](https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml) -that defines what file extensions need to be parsed. +that defines which file extensions must be parsed. -Excessive CPU use has been reported for files with the extension `.txt` and XML files with -a file extension that is not defined by the gem. +Files with the `.txt` extension and XML files with an extension not defined by the gem can take excessive CPU. -The workaround is to specify what language to assign to specific file extensions. +The workaround is to specify the language to assign to specific file extensions. The same approach should also allow misidentified file types to be fixed. -1. Identify which language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). - The entry for `Text` files, for example: +1. Identify the language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). + To add an entry for text files, for example: ```yaml Text: @@ -350,4 +277,17 @@ The same approach should also allow misidentified file types to be fixed. *.txt linguist-language=Text ``` - `*.txt` files have an entry in the heuristics file. The example above prevents parsing of these files. + `*.txt` files have an entry in the heuristics file. This example prevents parsing of these files. + +## Related topics + +- To lock files and prevent change conflicts, use [file locking](../file_lock.md). +- [Repository API](../../../api/repositories.md). +- [Find files](file_finder.md) in a repository. +- [Branches](branches/index.md). +- [File templates](web_editor.md#template-dropdowns). +- [Create a directory](web_editor.md#create-a-directory). +- [Start a merge request](web_editor.md#tips). +- [Find file history](git_history.md). +- [Identify changes by line (Git blame)](git_blame.md). +- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 4b649bab4d9..2ad1504aac3 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -20,10 +20,9 @@ rendered to HTML when viewed: Interactive features, including JavaScript plots, don't work when viewed in GitLab. -## Jupyter Hub as a GitLab Managed App - -You can deploy [Jupyter Hub as a GitLab managed app](../../../clusters/applications.md#jupyterhub). - ## Jupyter Git integration -Find out how to [leverage JupyterLab's Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). +Jupyter can be configured as an OAuth application with repository access, acting +on behalf of the authenticated user. See the +[Runbooks documentation](../../../project/clusters/runbooks/index.md) for an +example configuration. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 3bbe9e6cb66..e9f214f08ce 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -8,7 +8,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** Repository mirroring allows for the mirroring of repositories to and from external sources. You -can use it to mirror branches, tags, and commits between repositories. It's useful when you want to use +can use it to mirror branches, tags, and commits between repositories. It helps you use a repository outside of GitLab. A repository mirror at GitLab updates automatically. You can also manually trigger an update @@ -22,21 +22,22 @@ There are two kinds of repository mirroring supported by GitLab: When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. -Users with [Maintainer access](../../permissions.md) to the project can also force an +Users with the [Maintainer role](../../permissions.md) for the project can also force an immediate update, unless: - The mirror is already being updated. - The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. -For security reasons, the URL to the original repository is only displayed to users with -Maintainer or Owner permissions to the mirrored project. +For security reasons, the URL to the original repository is only displayed to users with the +[Maintainer role](../../permissions.md) or the [Owner role](../../permissions.md) for the mirrored +project. ## Use cases The following are some possible use cases for repository mirroring: - You migrated to GitLab but still need to keep your project in another source. In that case, you - can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + can set it up to mirror to GitLab (pull) and all the essential history of commits, tags, and branches are available in your GitLab instance. **(PREMIUM)** - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active @@ -65,9 +66,9 @@ For an existing project, you can set up push mirroring as follows:  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. +mirror diverging. -Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. +Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. The mirrored repository receives all changes only when: - Commits are pushed to GitLab. @@ -93,19 +94,19 @@ You can also create and modify project push mirrors through the By default, if any ref on the remote mirror has diverged from the local repository, the *entire push* fails, and no updates occur. -For example, if a repository has `master`, `develop`, and `stable` branches that +For example, if a repository has `main`, `develop`, and `stable` branches that have been mirrored to a remote, and then a new commit is added to `develop` on -the mirror, the next push attempt fails, leaving `master` and `stable` +the mirror, the next push attempt fails, leaving `main` and `stable` out-of-date despite not having diverged. No change on any branch can be mirrored until the divergence is resolved. With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, allowing `master` and `stable` to be updated. The mirror status +skipped, allowing `main` and `stable` to be updated. The mirror status reflects that `develop` has diverged and was skipped, and be marked as a failed update. NOTE: -After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). +After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md). ### Setting up a push mirror from GitLab to GitHub @@ -122,11 +123,15 @@ The repository pushes shortly thereafter. To force a push, select the **Update n ### Setting up a push mirror from GitLab to AWS CodeCommit -AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. +AWS CodeCommit push mirroring is the best way to connect GitLab repositories to +AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. -Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. +Each new AWS CodePipeline needs significant AWS infrastructure setup. It also +requires an individual pipeline per branch. -If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. +If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage +GitLab CI/CD pipelines and use the AWS CLI in the final job in `.gitlab-ci.yml` +to deploy to CodeDeploy. NOTE: GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. @@ -214,10 +219,9 @@ If it isn't working correctly, a red `error` tag appears and shows the error mes You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. -This is useful when a repository you're interested in is located on a different server, and you want -to be able to browse its content and its activity using the familiar GitLab interface. - -To configure mirror pulling for an existing project: +If a repository you're interested in is located on a different server, and you want +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/creating-a-personal-access-token) @@ -244,7 +248,7 @@ Because GitLab is now set to pull changes from the upstream repository, you shou directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. Changes pushed to the remote repository are pulled into the GitLab repository, either: -- Automatically within a certain period of time. +- Automatically in a certain period of time. - When a [forced update](#forcing-an-update) is initiated. WARNING: @@ -254,7 +258,7 @@ Deleted branches and tags in the upstream repository are not reflected in the Gi ### How it works -Once the pull mirroring feature has been enabled for a repository, the repository is added to a queue. +After the pull mirroring feature has been enabled for a repository, the repository is added to a queue. Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: @@ -556,7 +560,7 @@ Bidirectional mirroring should not be used as a permanent configuration. Refer t [Git Fusion](https://www.perforce.com/manuals/git-fusion/#Git-Fusion/section_avy_hyc_gl.html) provides a Git interface to [Perforce Helix](https://www.perforce.com/products) which can be used by GitLab to bidirectionally -mirror projects with GitLab. This may be useful in some situations when migrating from Perforce Helix +mirror projects with GitLab. This can help you in some situations when migrating from Perforce Helix to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 4e8e3f1bbce..cca8d770115 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -144,7 +144,7 @@ This dropdown contains the options **Create merge request and branch** and **Cre  After selecting one of these options, a new branch or branch and merge request -is created based on your project's default branch. By default, this branch is `master`. +is created based on your project's [default branch](branches/default.md). The branch name is based on an internal ID, and the issue title. The example screenshot above creates a branch named `2-make-static-site-auto-deploy-and-serve`. @@ -152,7 +152,7 @@ screenshot above creates a branch named When you click the **Create branch** button in an empty repository project, GitLab performs these actions: -- Creates a `master` branch. +- Creates a default branch. - Commits a blank `README.md` file to it. - Creates and redirects you to a new branch based on the issue title. - _If your project is [configured with a deployment service](../integrations/overview.md) like Kubernetes,_ @@ -183,7 +183,7 @@ request, you can create a new branch upfront.  You can now make changes to any files, as needed. When you're ready to merge -the changes back to `master`, you can use the widget at the top of the screen. +the changes back to your [default branch](branches/default.md), you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or modify files. @@ -211,7 +211,7 @@ SHA: ## Tips When creating or uploading a new file or creating a new directory, you can -trigger a new merge request rather than committing directly to `master`: +trigger a new merge request rather than committing directly to your default branch: 1. Enter a new branch name in the **Target branch** field. 1. GitLab displays the **Start a new merge request with these changes** check box. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index f5fa6e37d1c..890784cecf5 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Project import/export +# Project import/export **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. > - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. @@ -24,9 +24,9 @@ See also: To set up a project import/export: - 1. Navigate to **Admin Area > Settings > Visibility and access controls**. - 1. Scroll to **Import sources** - 1. Enable desired **Import sources** + 1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. + 1. Scroll to **Import sources**. + 1. Enable the desired **Import sources**. ## Important notes @@ -43,7 +43,7 @@ Note the following: and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. - Group members are exported as project members, as long as the user has maintainer or administrator access to the group where the exported project lives. -- Project members with owner access are imported as maintainers. +- Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. @@ -139,7 +139,7 @@ The following items are **not** exported: NOTE: For more details on the specific data persisted in a project export, see the -[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/project/import_export.yml) file. +[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. ## Exporting a project and its data diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index d3177aa7585..03a77e42765 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -30,7 +30,7 @@ Adjust your project's name, description, avatar, [default branch](../repository/  -The project description also partially supports [standard Markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. #### Compliance frameworks **(PREMIUM)** @@ -79,7 +79,7 @@ Example `.compliance-gitlab-ci.yml` ```yaml # Allows compliance team to control the ordering and interweaving of stages/jobs. # Stages without jobs defined will remain hidden. -stages: +stages: - pre-compliance - build - test @@ -93,26 +93,82 @@ variables: # can be overriden by a developer's local .gitlab-ci.yml sast: # none of these attributes can be overriden by a developer's local .gitlab-ci.yml variables: FOO: sast + image: ruby:2.6 stage: pre-compliance + rules: + - when: always + allow_failure: false + before_script: + - "# No before scripts." script: - echo "running $FOO" + after_script: + - "# No after scripts." sanity check: + image: ruby:2.6 stage: pre-deploy-compliance + rules: + - when: always + allow_failure: false + before_script: + - "# No before scripts." script: - echo "running $FOO" + after_script: + - "# No after scripts." audit trail: + image: ruby:2.6 stage: post-compliance + rules: + - when: always + allow_failure: false + before_script: + - "# No before scripts." script: - echo "running $FOO" + after_script: + - "# No after scripts." include: # Execute individual project's configuration project: '$CI_PROJECT_PATH' - file: '$CI_PROJECT_CONFIG_PATH' + file: '$CI_CONFIG_PATH' ``` +##### Ensure compliance jobs are always run + +Compliance pipelines use GitLab CI/CD to give you an incredible amount of flexibility +for defining any sort of compliance jobs you like. Depending on your goals, these jobs +can be configured to be: + +- Modified by users. +- Non-modifiable. + +At a high-level, if a value in a compliance job: + +- Is set, it cannot be changed or overridden by project-level configurations. +- Is not set, a project-level configuration may set. + +Either might be wanted or not depending on your use case. + +There are a few best practices for ensuring that these jobs are always run exactly +as you define them and that downstream, project-level pipeline configurations +cannot change them: + +- Add a `rules:when:always` block to each of your compliance jobs. This ensures they are + non-modifiable and are always run. +- Explicitly set any variables the job references. This: + - Ensures that project-level pipeline configurations do not set them and alter their + behavior. + - Includes any jobs that drive the logic of your job. +- 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/README.md#job-keywords). + This ensures that your job uses the settings you intend and that they are not overriden by + project-level pipelines. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -123,7 +179,7 @@ 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#project-membership-and-requesting-access). +[Allow users to request access](../members/index.md#prevent-users-from-requesting-access-to-a-project). Use the switches to enable or disable the following features: @@ -193,6 +249,7 @@ Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.md)). - Add merge request [description templates](../description_templates.md#description-templates). - Enable [merge request approvals](../merge_requests/approvals/index.md). +- Enable [status checks](../merge_requests/status_checks.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). @@ -242,10 +299,11 @@ To find an archived project: 1. If you: - Have the project's URL, open the project's page in your browser. - Don't have the project's URL: - 1. Click **Projects > Explore projects**. - 1. In the **Sort projects** dropdown box, select **Show archived projects**. - 1. In the **Filter by name** field, provide the project's name. - 1. Click the link to the project to open its **Details** page. + 1. On the top bar, select **Menu > Project**. + 1. Select **Explore projects**. + 1. In the **Sort projects** dropdown box, select **Show archived projects**. + 1. In the **Filter by name** field, provide the project's name. + 1. Click the link to the project to open its **Details** page. Next, to unarchive the project: @@ -273,7 +331,7 @@ To rename a repository: Remember that this can have unintended side effects since everyone with the old URL can't push or pull. Read more about what happens with the -[redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths). +[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). #### Transferring an existing project into another namespace @@ -283,7 +341,7 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -- You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group. +- You have at least the Maintainer** role 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. @@ -297,7 +355,7 @@ To transfer a project: Once done, you are redirected to the new project's namespace. At this point, read what happens with the -[redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). +[redirects from the old project to the new one](../repository/index.md#what-happens-when-a-repository-path-changes). NOTE: GitLab administrators can use the administration interface to move any project to any @@ -306,7 +364,7 @@ namespace if needed. #### Delete a project NOTE: -Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. +Only project Owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. To delete a project: @@ -318,10 +376,10 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -group owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group -to be deleted after a delayed period. -When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). + group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group + to be deleted after a delayed period. + When enabled, actual deletion happens after number of days + specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). WARNING: The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to @@ -354,10 +412,10 @@ 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. -## Operations settings +## Monitor settings ### Alerts diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index d37e6144ab3..be8a961d6c0 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -81,6 +81,8 @@ the following table. ## Enable or disable project access token creation +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) in GitLab 13.11. + You may enable or disable project access token creation for all projects in a group in **Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation**. Even when creation is disabled, you can still use and revoke existing project access tokens. This setting is available only on top-level groups. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index df76c4682f3..3c9b0341661 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -20,7 +20,7 @@ Time Tracking allows you to: - Record the time spent working on an issue or a merge request. - Add an estimate of the amount of time needed to complete an issue or a merge request. -- View a breakdown of time spent working on an issue or a merge request. +- View a breakdown of time spent working on an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. @@ -82,6 +82,10 @@ To remove all the time spent at once, use `/remove_time_spent`. You can view a breakdown of time spent on an issue or merge request. +Prerequisites: + +- You must have at least the [Reporter role](../permissions.md#project-members-permissions) for a project. + To view a time tracking report, go to an issue or a merge request and select **Time tracking report** in the right sidebar. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 73aed1244db..0e597725611 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -259,19 +259,27 @@ Additionally, for public projects an **Open in CodeSandbox** button is available to transfer the contents of the project into a public CodeSandbox project to quickly share your project with others. -### Enabling Live Preview +### Enable Live Preview -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268288) in GitLab 12.9, third-party assets and libraries required for Live Preview are hosted at `https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries are still served from other third-party services which may or may not be desirable in your environment. +With Live Preview enabled, you can preview projects with a `package.json` file and +a `main` entry point inside the Web IDE. -The Live Preview feature needs to be enabled in the GitLab instance's -Admin Area. Live Preview is enabled for all projects on -GitLab.com +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. Scroll to **Web IDE** and select **Expand**: +  +1. Select **Enable Live Preview** and select **Save changes**. -After you have done that, you can preview projects with a `package.json` file and -a `main` entry point inside the Web IDE. An example `package.json` is shown -below. +[In GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/268288), +third-party assets and libraries required for Live Preview are hosted at +`https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries +are still served from other third-party services, which may or may not be desirable +in your environment. + +An example `package.json`: ```json { diff --git a/doc/user/project/wiki/img/content_editor_v14.0.png b/doc/user/project/wiki/img/content_editor_v14.0.png Binary files differnew file mode 100644 index 00000000000..b44a633073d --- /dev/null +++ b/doc/user/project/wiki/img/content_editor_v14.0.png diff --git a/doc/user/project/wiki/img/use_new_editor_button_v14.0.png b/doc/user/project/wiki/img/use_new_editor_button_v14.0.png Binary files differnew file mode 100644 index 00000000000..d9a5cf83302 --- /dev/null +++ b/doc/user/project/wiki/img/use_new_editor_button_v14.0.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 22915efef94..ed6a51665bd 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -7,7 +7,7 @@ type: reference, how-to # Wiki **(FREE)** -If you don't want to keep your documentation in your repository, but you do want +If you don't want to keep your documentation in your repository, but you want to keep it in the same project as your code, you can use the wiki GitLab provides in each GitLab project. Every wiki is a separate Git repository, so you can create wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). @@ -34,8 +34,8 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se When a wiki is created, it is empty. On your first visit, create the landing page users see when viewing the wiki: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, then **Create your first page**. +1. Go to your project or group and select **Wiki**. +1. Select **Create your first page**. 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 **Commit message**. Git requires a commit message, so GitLab creates one @@ -46,8 +46,7 @@ users see when viewing the wiki: Users with Developer [permissions](../../permissions.md) can create new wiki pages: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**. +1. Go to your project or group and select **Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. 1. Add a title for your new page. Page titles use @@ -111,8 +110,8 @@ may not be able to check out the wiki locally afterward. You need Developer [permissions](../../permissions.md) or higher to edit a wiki page: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the page you want to edit. +1. Go to your project or group and select **Wiki**. +1. Go to the page you want to edit. 1. Select the edit icon (**{pencil}**). 1. Edit the content. 1. Select **Save changes**. @@ -124,10 +123,11 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page: +You need the [Maintainer role](../../permissions.md) or higher to delete a wiki page: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the page you want to delete. +1. Go to your project or group and select **Wiki**. +1. Go to the page you want to delete. +1. Select the edit icon (**{pencil}**). 1. Select **Delete page**. 1. Confirm the deletion. @@ -135,8 +135,8 @@ You need Maintainer [permissions](../../permissions.md) or higher to delete a wi You need Developer [permissions](../../permissions.md) or higher to move a wiki page: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the page you want to move. +1. Go to your project or group and select **Wiki**. +1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. For example, if you have a wiki page called `about` under `company` and you want to move it to the wiki's root, @@ -164,8 +164,8 @@ From the history page you can see: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the wiki page you're interested in. +1. Go to your project or group and select **Wiki**. +1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in. @@ -192,8 +192,7 @@ You need Developer [permissions](../../permissions.md) or higher to customize th navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**. +1. Go to your project or group and select **Wiki**. 1. In the top right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -243,7 +242,7 @@ and above. Group wiki repositories can be moved using the To add a link to an external wiki from a project's left sidebar: -1. In your project, go to **Settings > Integrations**. +1. Go to your project and select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. 1. (Optional) Select **Test settings** to verify the connection. @@ -253,21 +252,21 @@ You can now see the **External wiki** option from your project's left sidebar. When you enable this integration, the link to the external -wiki won't replace the link to the internal wiki. +wiki doesn't replace the link to the internal wiki. To hide the internal wiki from the sidebar, [disable the project's wiki](#disable-the-projects-wiki). To hide the link to an external wiki: -1. In your project, go to **Settings > Integrations**. +1. Go to your project and select **Settings > Integrations**. 1. Select **External wiki**. -1. Unselect **Enable integration**. +1. In the **Enable integration** section, clear the **Active** checkbox. 1. Select **Save changes**. ## Disable the project's wiki To disable a project's internal wiki: -1. In your project, go to **Settings > General**. +1. Go to your project and select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). 1. Select **Save changes**. @@ -282,6 +281,47 @@ Previously added wiki pages are preserved in case you want to re-enable the wiki. To re-enable it, repeat the process to disable the wiki but toggle it on (in blue). +## Content Editor **(FREE)** + +> - [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). +The Content Editor is under active development, and is not yet the default editing +experience in the Wiki. To opt in for the new editor: + +1. Create a new wiki page, or edit an existing one. +1. Ensure the wiki page uses the Markdown format. Other formats are not yet supported. +1. Below the **Format** select box, select **Use the new editor**: + +  + +### Use the Content Editor + +1. [Create](#create-a-new-wiki-page) a new wiki page, or [edit](#edit-a-wiki-page) an existing one. +1. Select **Markdown** as your format. +1. Below the **Format** select box, select **Use new editor**. +1. Customize your page's content using the various formatting options available in the content editor. +1. Select **Create page** for a new page, or **Save changes** for an existing page: + +  + +### Switch back to the old editor + +1. *If you're editing the page in the content editor,* scroll to **Content**. +1. Select **Switch me back to the classic editor**. +1. Select **Switch to classic editor** in the confirmation popup to confirm. + +When you switch back to the old editor, any unsaved changes are lost. + +### GitLab Flavored Markdown support + +Supporting all GitLab Flavored Markdown content types in the Content Editor is a work in progress. +For the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: + +- [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. +- [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. + ## Resources - [Wiki settings for administrators](../../../administration/wikis/index.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index ddca0b64f81..a0b20f5c86d 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -13,8 +13,8 @@ code are saved in projects, and most features are in the scope of projects. You can explore other popular projects available on GitLab. To explore projects: -1. Click **Projects** in the navigation bar. -1. Click **Explore Projects**. +1. On the top bar, select **Menu > Project**. +1. Select **Explore Projects**. GitLab displays a list of projects, sorted by last updated date. To view projects with the most [stars](#star-a-project), click **Most stars**. To view @@ -84,6 +84,7 @@ Built-in templates are project templates that are: - Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups. - Released with GitLab. +- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates). To use a built-in template on the **New project** page: @@ -196,8 +197,8 @@ To star a project: To view your starred projects: -1. Click **Projects** in the navigation bar. -1. Click **Starred Projects**. +1. On the top bar, select **Menu > Project**. +1. Select **Starred Projects**. 1. GitLab displays information about your starred projects, including: - Project description, including name, description, and icon @@ -227,10 +228,16 @@ Read through the documentation on [project settings](settings/index.md). ## Project activity -To view the activity of a project, navigate to **Project overview > Activity**. -From there, you can click on the tabs to see **All** the activity, or see it -filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, -**Team**, and **Wiki**. +To view the activity of a project: + +1. On the left sidebar, select **Project information > Activity**. +1. Select a tab to view **All** the activity, or to filter it by any of these criteria: + - **Push events** + - **Merge events** + - **Issue events** + - **Comments** + - **Team** + - **Wiki** ### Leave a project @@ -333,7 +340,7 @@ For public projects, and to members of internal and private projects with [permissions to view the project's code](../permissions.md#project-members-permissions): - The content of a - [`README` or an index file](repository/#repository-readme-and-index-files) + [`README` or an index file](repository/index.md#readme-and-index-files) is displayed (if any), followed by the list of directories in the project's repository. - If the project doesn't contain either of these files, the |
