diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-05 19:20:45 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-05 19:20:45 +0300 |
commit | d298fad0c0564454271cba11e6f20c19681534ac (patch) | |
tree | 0a19d07d8b3bdd2574617305c300e404f2ace581 /doc/user/project | |
parent | c9f9eec79cab801a50db698f682aacffbedf07f7 (diff) |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc41
Diffstat (limited to 'doc/user/project')
175 files changed, 1352 insertions, 1478 deletions
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 1aa040c9cb8..e3b52e99a89 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -57,4 +57,4 @@ If you continue to type, `@le`, the popup list changes to the following. The popup now only includes users where `le` appears in their username, or a word in their name. -![Popup list which includes users whose username or name contains the string `le`](img/autocomplete_characters_example2_v12_0.png) +![Popup list which includes users whose username or name contains the string](img/autocomplete_characters_example2_v12_0.png) diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md deleted file mode 100644 index e7572b4ff1f..00000000000 --- a/doc/user/project/builds/artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../pipelines/job_artifacts.md' ---- - -This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index a29c0754d31..19f17ad91d7 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -21,6 +21,10 @@ Only the items visible on the current page are selected for bulk editing (up to ## Bulk edit issues at the project level +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + NOTE: You need a permission level of [Reporter or higher](../permissions.md) to manage issues. @@ -28,13 +32,12 @@ When bulk editing issues in a project, you can edit the following attributes: - Status (open/closed) - Assignee -- Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in - [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.) **(PREMIUM)** -- Milestone -- Labels -- Health status ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in - [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.) **(ULTIMATE)** -- Subscriptions +- [Epic](../group/epics/index.md) +- [Milestone](milestones/index.md) +- [Labels](labels.md) +- [Health status](issues/index.md#health-status) +- Notification subscription +- [Iteration](../group/iterations/index.md) To update multiple project issues at the same time: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 85ac641f6e4..f7394093a3a 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,10 +4,10 @@ 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 --- -# Canary Deployments **(CORE)** +# Canary Deployments **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Core in 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of @@ -72,7 +72,7 @@ can easily notice them. ### Advanced traffic control with Canary Ingress > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Free in GitLab 13.8. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md deleted file mode 100644 index 57747be3859..00000000000 --- a/doc/user/project/ci_cd_for_external_repo.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../ci/ci_cd_for_external_repos/index.md' ---- - -This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 9047e564598..94aedb1cdab 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding EKS clusters +# Adding EKS clusters **(CORE)** GitLab supports adding new and existing EKS clusters. @@ -20,7 +20,7 @@ requirements are met: - `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) for access to the EKS cluster. -### Additional requirements for self-managed instances **(CORE ONLY)** +### Additional requirements for self-managed instances **(FREE SELF)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index e3e6efc887f..421a59db92c 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding GKE clusters +# Adding GKE clusters **(CORE)** GitLab supports adding new and existing GKE clusters. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index beb8b71b917..7f4d25b7eca 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding and removing Kubernetes clusters +# Adding and removing Kubernetes clusters **(CORE)** GitLab offers integrated cluster creation for the following Kubernetes providers: @@ -40,7 +40,7 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - [Maintainer access to 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. **(CORE ONLY)** + cluster. **(FREE SELF)** ## Access controls diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md deleted file mode 100644 index e38fbb871c1..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../add_eks_clusters.md#existing-eks-cluster' ---- - -This document was moved to [another location](../add_eks_clusters.md#existing-eks-cluster). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a06846e33a6..ab83da3a975 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,7 +4,7 @@ group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Kubernetes clusters +# Kubernetes clusters **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in @@ -33,8 +33,10 @@ integrated at the [group level](../../group/clusters/index.md) or To view your project level Kubernetes clusters, navigate to **Operations > 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 nodes count and rough estimates -of memory and CPU usage. +and view information about your existing clusters, such as: + +- Nodes count. +- Rough estimates of memory and CPU usage. ## Setting up @@ -72,13 +74,12 @@ to: ### Multiple Kubernetes clusters > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, -like dev, staging, production, and so on. - -Simply add another cluster, like you did the first time, and make sure to +like development, staging, production, and so on. +Add another cluster, like you did the first time, and make sure to [set an environment scope](#setting-the-environment-scope) that differentiates the new cluster from the rest. @@ -165,7 +166,7 @@ details about the created resources. If you choose to manage your own cluster, project-specific resources aren't created automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -for your deployment jobs to use; otherwise a namespace is created for you. +for your deployment jobs to use. Otherwise, a namespace is created for you. #### Important notes @@ -182,10 +183,10 @@ Note the following with GitLab and clusters: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. -If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached +If you allow GitLab to manage your cluster, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you modify these resources in your cluster manually, this cache can fall out of sync with -your cluster, which can cause deployment jobs to fail. +your cluster. This can cause deployment jobs to fail. To clear the cache: @@ -204,12 +205,61 @@ Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an env 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)), +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: - 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`. +To determine the external Ingress IP address, or external Ingress hostname: + +- *If the cluster is on GKE*: + 1. Click the **Google Kubernetes Engine** link in the **Advanced settings**, + or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/). + 1. Select the proper project and cluster. + 1. Click **Connect** + 1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**. + +- *If the cluster is not on GKE*: Follow the specific instructions for your + Kubernetes provider to configure `kubectl` with the right credentials. + The output of the following examples show the external endpoint of your + cluster. This information can then be used to set up DNS entries and forwarding + rules that allow external access to your deployed applications. + +Depending an your Ingress, the external IP address can be retrieved in various ways. +This list provides a generic solution, and some GitLab-specific approaches: + +- In general, you can list the IP addresses of all load balancers by running: + + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` + +- If you installed Ingress using the **Applications**, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` + +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` + + If you use EKS, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which incurs additional AWS costs. + +- Istio/Knative uses a different command. Run: + + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + +If you see a trailing `%` on some Kubernetes versions, do not include it. + ## Installing applications GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, @@ -224,10 +274,10 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) the Kubernetes project integration must be enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled. However, Kubernetes clusters can be used without Auto DevOps. -[Read more about Auto DevOps](../../../topics/autodevops/index.md) +[Read more about Auto DevOps](../../../topics/autodevops/index.md). ## Deploying to a Kubernetes cluster @@ -260,9 +310,9 @@ following command in your deployment job script, for Kubernetes to access the re kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - ``` -The Kubernetes cluster integration exposes the following +The Kubernetes cluster integration exposes these [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment to deployment jobs, which are jobs that have +GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md#defining-environments). | Variable | Description | @@ -303,7 +353,7 @@ When you customize the namespace, existing environments remain linked to their c namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). WARNING: -By default, anyone who can create a deployment job can access any CI variable within +By default, anyone who can create a deployment job can access any CI 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 @@ -327,8 +377,8 @@ the need to leave GitLab. #### Deploy Boards GitLab Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, -displaying the status of the pods in the deployment. Developers and other +status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes. +They display the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -336,7 +386,7 @@ workflow they already use without any need to access Kubernetes. #### Viewing pod logs -GitLab makes it easy to view the logs of running pods in connected Kubernetes +GitLab enables you to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. @@ -349,7 +399,7 @@ to manage console tools or jump to a different interface. When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new -shell session within your existing containers. To use this integration, you +shell session in your existing containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any deployments, replica sets, and pods are annotated with: @@ -402,7 +452,7 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of ### Visualizing cluster health > - [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 Core in 13.2. +> - [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. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 2523dc3e0a2..349040e0bf6 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -4,10 +4,10 @@ group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Kubernetes Logs +# Kubernetes Logs **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. +> - [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 [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab 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 8299844e511..a7cdd73acd7 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -28,10 +28,9 @@ chart. - GitLab managed installation of Cilium. - Support for L3, L4, and L7 policies. - Ability to export logs to a SIEM. -- Statistics page showing volume of packets processed and dropped over time (Gold/Ultimate users - only). +- Statistics page showing volume of packets processed and dropped over time (Ultimate users only). - Management of NetworkPolicies through code in a project (Available for auto DevOps users only). -- Management of CiliumNetworkPolicies through a UI policy manager (Gold/Ultimate users only). +- Management of CiliumNetworkPolicies through a UI policy manager (Ultimate users only). ## Supported container orchestrators 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 10f9380a1f2..e530f0dfcda 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 @@ -46,11 +46,11 @@ Network Policies can be managed through GitLab in one of two ways: - Management through a YAML file in each application's project (for projects using Auto DevOps). For more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more - information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate/Gold only). + information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only). Each method has benefits and drawbacks: -| | YAML method | UI method (Ultimate/Gold only) | +| | YAML method | UI method (Ultimate only) | |--|:------------|:-------------------------------| | **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | | **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. | 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 index e9a05b58fec..e7d8d591510 100644 --- 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 @@ -43,7 +43,7 @@ Google Kubernetes Engine integration. All you have to do is [follow this link](h ## Creating a new project from a template We use a GitLab project templates to get started. As the name suggests, -those projects provide a barebones application built on some well-known frameworks. +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**. @@ -55,7 +55,7 @@ those projects provide a barebones application built on some well-known framewor 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 Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + [GitLab Ultimate plan](https://about.gitlab.com/pricing/). ![Create project](../../../../../topics/autodevops/img/guide_create_project_v12_3.png) diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 8572ab850e4..18c8ba9626f 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Runbooks +# Runbooks **(CORE)** Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index a52d3400aa2..2d0ed3cd207 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploying AWS Lambda function using GitLab CI/CD +# Deploying AWS Lambda function using GitLab CI/CD **(CORE)** GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. @@ -74,7 +74,7 @@ Place this code in the file `src/handler.js`. In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. -You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> +You can learn more about the [AWS Lambda Node.js function handler](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html) and all its various options in its documentation. #### Creating a `serverless.yml` file diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 043c5e4ca79..336813b5ba5 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Serverless +# Serverless **(CORE)** > Introduced in GitLab 11.5. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 63ea84e42c9..1e1938854df 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -5,11 +5,11 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Owners **(STARTER)** +# Code Owners **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) -in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. +> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. +> - Moved to GitLab Premium in 13.9. ## Introduction @@ -18,7 +18,7 @@ to find out who should review or approve merge requests. Additionally, if you have a question over a specific file or code block, it may be difficult to know who to find the answer from. -GitLab Code Owners is a feature to define who owns specific +The GitLab Code Owners feature defines who owns specific files or paths in a repository, allowing other users to understand who is responsible for each file or path. @@ -32,7 +32,7 @@ the process of finding the right reviewers and approvers for a given merge request. In larger organizations or popular open source projects, Code Owners -can also be useful to understand who to contact if you have +can help you understand who to contact if you have a question that may not be related to code review or a merge request approval. @@ -49,12 +49,12 @@ You can choose to add the `CODEOWNERS` file in three places: - Inside the `docs/` directory The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners -in a feature branch, they won't be valid in the main branch until the feature branch is merged. +in a feature branch, the changes aren't valid in the main branch until the feature branch is merged. If you introduce new files to your repository and you want to identify the code owners for that file, -you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same -branch), GitLab will count the owners as soon as the branch is merged. If -you don't, you can do that later, but your new files will not belong to anyone until you update your +you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same +branch), GitLab counts the owners as soon as the branch is merged. If +you don't, you can do that later, but your new files don't belong to anyone until you update your `CODEOWNERS` file in the TARGET branch. When a file matches multiple entries in the `CODEOWNERS` file, @@ -73,29 +73,32 @@ The user that would show for `README.md` would be `@user2`. ## Approvals by Code Owners -Once you've added Code Owners to a project, you can configure it to +After you've added Code Owners to a project, you can configure it to be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** -Developer or higher [permissions](../permissions.md) are required in order to +Developer or higher [permissions](../permissions.md) are required to approve a merge request. -Once set, Code Owners are displayed in merge requests widgets: +After it's set, Code Owners are displayed in merge request widgets: ![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png) -While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), -it can also be used as the sole driver of merge request approvals -(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). -To do so, create the file in one of the three locations specified above and -set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). -Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) -to specify the actual owners and granular permissions. +While you can use the `CODEOWNERS` file in addition to Merge Request +[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), +you can also use it as the sole driver of merge request approvals +without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules): + +1. Create the file in one of the three locations specified above. +1. Set the code owners as required approvers for + [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). +1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) + to specify the actual owners and granular permissions. Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) -will prevent any user who is not specified in the `CODEOWNERS` file from pushing +prevents any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as administrators don't have to restrict developers from pushing directly to the @@ -114,13 +117,13 @@ in the `.gitignore` file followed by one or more of: - The `@name` of one or more groups that should be owners of the file. - Lines starting with `#` are ignored. -The order in which the paths are defined is significant: the last pattern that -matches a given path will be used to find the code owners. +The path definition order is significant: the last pattern +matching a given path is used to find the code owners. ### Groups as Code Owners -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1. -> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. Groups and subgroups members are inherited as eligible Code Owners to a project, as long as the hierarchy is respected. @@ -131,7 +134,7 @@ suppose you have a project called "Project A" within the group and a "Project B" within the subgroup. The eligible Code Owners to Project B are both the members of the Group X and -the Subgroup Y. And the eligible Code Owners to the Project A are just the +the Subgroup Y. The eligible Code Owners to the Project A are just the members of the Group X, given that Project A doesn't belong to the Subgroup Y: ![Eligible Code Owners](img/code_owners_members_v13_4.png) @@ -142,9 +145,9 @@ Code Owners: ![Invite subgroup members to become eligible Code Owners](img/code_owners_invite_members_v13_4.png) -Once invited, any member (`@user`) of the group or subgroup can be set -as Code Owner to files of the Project A or B, as well as the entire Group X -(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below: +After being invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, and the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows: ```plaintext # A member of the group or subgroup as Code Owner to a file @@ -162,7 +165,7 @@ file.md @group-x @group-x/subgroup-y ### Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better @@ -185,8 +188,8 @@ changes, to set their own independent patterns by specifying discrete sections i teams can be added as reviewers. Sections can be added to `CODEOWNERS` files as a new line with the name of the -section inside square brackets. Every entry following it is assigned to that -section. The following example would create 2 Code Owner rules for the "README +section inside square brackets. Every entry following is assigned to that +section. The following example would create two Code Owner rules for the "README Owners" section: ```plaintext @@ -196,7 +199,7 @@ internal/README.md @user2 ``` Multiple sections can be used, even with matching file or directory patterns. -Reusing the same section name will group the results together under the same +Reusing the same section name groups the results together under the same section, with the most specific rule or last matching pattern being used. For example, consider the following entries in a `CODEOWNERS` file: @@ -213,7 +216,7 @@ model/db @gl-database README.md @gl-docs ``` -This will result in 3 entries under the "Documentation" section header, and 2 +This results in three entries under the "Documentation" section header, and two entries under "Database". Case is not considered when combining sections, so in this example, entries defined under the sections "Documentation" and "DOCUMENTATION" would be combined into one, using the case of the first instance @@ -227,9 +230,11 @@ the rules for "Groups" and "Documentation" sections: #### Optional Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9. -When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example: +To make a certain section optional, add a code owners section prepended with the +caret `^` character. Approvals from owners listed in the section are **not** required. For example: ```plaintext [Documentation] @@ -242,13 +247,13 @@ When you want to make a certain section optional, you can do so by adding a code *.go @root ``` -The optional code owners section will be displayed in merge requests under the **Approval Rules** area: +The optional code owners section displays in merge requests under the **Approval Rules** area: ![MR widget - Optional Code Owners Sections](img/optional_code_owners_sections_v13_8.png) -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. -For example, the code owners of the "Documentation" section below will still be required to approve merge requests: +For example, the code owners of the "Documentation" section below is still required to approve merge requests: ```plaintext [Documentation] @@ -264,12 +269,12 @@ For example, the code owners of the "Documentation" section below will still be *.txt @root ``` -Optional sections in the code owners file are currently treated as optional only -when changes are submitted via merge requests. If a change is submitted directly -to the protected branch, approval from code owners will still be required, even if the -section is marked as optional. We plan to change this in a +Optional sections in the code owners file are treated as optional only +when changes are submitted by using merge requests. If a change is submitted directly +to the protected branch, approval from code owners is still required, even if the +section is marked as optional. We plan to change this behavior in a [future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638), -where direct pushes to the protected branch will be allowed for sections marked as optional. +and allow direct pushes to the protected branch for sections marked as optional. ## Example `CODEOWNERS` file diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md deleted file mode 100644 index 17e86b6d7e8..00000000000 --- a/doc/user/project/container_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../packages/container_registry/index.md' ---- - -This document was moved to [another location](../packages/container_registry/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md deleted file mode 100644 index 5c235f6708b..00000000000 --- a/doc/user/project/cycle_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/value_stream_analytics.md' ---- - -This document was moved to [another location](../analytics/value_stream_analytics.md) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 831a8803622..72695580d9d 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(CORE)** +# Deploy Boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Core in 13.8. +> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Free in 13.8. GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -93,7 +93,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can lookup the proper environment in a cluster/namespace which may have more than one. These resources should be contained in the namespace defined in - the Kubernetes service setting. You can use an [Autodeploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` + the Kubernetes service setting. You can use an [Auto deploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` template which has predefined stages and commands to use, and automatically applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside @@ -158,7 +158,7 @@ version of your application. ## Further reading -- [GitLab Autodeploy](../../topics/autodevops/stages.md#auto-deploy) +- [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy) - [GitLab CI/CD environment variables](../../ci/variables/README.md) - [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 93ed1030e1f..1bd68fc5c1e 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -7,10 +7,10 @@ type: howto, reference # Deploy Keys -Deploy keys allow read-only or read-write (if enabled) access to one or -more repositories, by importing an SSH public key to your GitLab instance. +Deploy keys allow read-only or read-write access to your +repositories by importing an SSH public key into your GitLab instance. -This is useful for cloning repositories to your Continuous +This is useful, for example, for cloning repositories to your Continuous Integration (CI) server. By using deploy keys, you don't have to set up a fake user account. @@ -82,7 +82,7 @@ can add or enable a deploy key for a project repository: 1. Navigate to the project's **Settings > Repository** page. 1. Expand the **Deploy Keys** section. 1. Specify a title for the new deploy key and paste your public SSH key. -1. (Optional) Check **Write access allowed** to allow `read-write` access. Leave it unchecked for `read-only` access. +1. (Optional) Check **Grant write permissions to this key** to allow `read-write` access. Leave it unchecked for `read-only` access. There are three lists of Project Deploy Keys: diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5a62730d989..6f05c40eefc 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -67,7 +67,7 @@ following table along with GitLab version it was introduced in: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. -The default username format is `gitlab+deploy-token-#{n}`. Some tools or +The default username format is `gitlab+deploy-token-{n}`. Some tools or platforms may not support this format; in this case you can specify a custom username to be used when creating the deploy token. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 3108bdda7a0..a7ce48b6487 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,16 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Description templates ->[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. We all know that a properly submitted issue is more likely to be addressed in a timely manner by the developers of a project. -Description templates allow you to define context-specific templates for issue -and merge request description fields for your project, as well as help filter -out a lot of unnecessary noise from issues. - -## Overview +With description templates, you can define context-specific templates for issue and merge request +description fields for your project, and filter out unnecessary noise from issues. By using the description templates, users that create a new issue or merge request can select a description template to help them communicate with other @@ -28,7 +25,10 @@ Description templates must be written in [Markdown](../markdown.md) and stored in your project's repository under a directory named `.gitlab`. Only the templates of the default branch are taken into account. -## Use-cases +To learn how to create templates for various file types in groups, visit +[Group file templates](../group/index.md#group-file-templates). + +## Use cases - Add a template to be used in every issue for a specific project, giving instructions and guidelines, requiring for information specific to that subject. @@ -39,6 +39,8 @@ templates of the default branch are taken into account. images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. +- You can use an [issue description template](#creating-issue-templates) as a + [Service Desk email template](service_desk.md#new-service-desk-issues). ## Creating issue templates @@ -47,20 +49,20 @@ directory in your repository. Commit and push to your default branch. To create a Markdown file: - 1. Click the `+` button next to `master` and click **New file**. - 1. Add the name of your issue template to the **File name** text field next to `master`. - Make sure that your file has the `.md` extension, for - example `feature_request.md` or `Feature Request.md`. - 1. Commit and push to your default branch. +1. Click the `+` button next to `master` and click **New file**. +1. Add the name of your issue template to the **File name** text field next to `master`. + Make sure that your file has the `.md` extension, for + example `feature_request.md` or `Feature Request.md`. +1. Commit and push to your default branch. If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it. To create the `.gitlab/issue_templates` directory: - 1. Click the `+` button next to `master` and select **New directory**. - 1. Name this new directory `.gitlab` and commit to your default branch. - 1. Click the `+` button next to `master` again and select **New directory**.This time, n - 1. Name your directory `issue_templates` and commit to your default branch. +1. Click the `+` button next to `master` and select **New directory**. +1. Name this new directory `.gitlab` and commit to your default branch. +1. Click the `+` button next to `master` again and select **New directory**. +1. Name your directory `issue_templates` and commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. @@ -80,17 +82,17 @@ to the issue description field. The **Reset template** button discards any changes you made after picking the template and returns it to its initial status. NOTE: -You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. +You can create shortcut links to create an issue using a designated template. +For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. ![Description templates](img/description_templates.png) ## Setting a default template for merge requests and issues **(STARTER)** -> - This feature was introduced before [description templates](#overview) and is available in [GitLab Starter](https://about.gitlab.com/pricing/). It can be enabled in the project's settings. -> - Templates for issues were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28) in GitLab EE 8.1. -> - Templates for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/commit/7478ece8b48e80782b5465b96c79f85cc91d391b) in GitLab EE 6.9. +> - Templates for merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/commit/7478ece8b48e80782b5465b96c79f85cc91d391b) in GitLab 6.9. +> - Templates for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28) in GitLab 8.1. -The visibility of issues and/or merge requests should be set to either "Everyone +The visibility of issues or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the template text areas don't show. This is the default behavior, so in most cases you should be fine. @@ -113,52 +115,46 @@ pre-filled with the text you entered in the template(s). ## Description template example -We make use of Description Templates for Issues and Merge Requests within the GitLab Community -Edition project. Please refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) -for some examples. +We make use of description templates for issues and merge requests in the GitLab project. +For some examples, refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab). NOTE: -It's possible to use [quick actions](quick_actions.md) within description templates to quickly add +It's possible to use [quick actions](quick_actions.md) in description templates to quickly add labels, assignees, and milestones. The quick actions are only executed if the user submitting the issue or merge request has the permissions to perform the relevant actions. Here is an example of a Bug report template: -```plaintext -Summary +```markdown +## Summary (Summarize the bug encountered concisely) - -Steps to reproduce +## Steps to reproduce (How one can reproduce the issue - this is very important) +## Example Project -Example Project - -(If possible, please create an example project here on GitLab.com that exhibits the problematic behaviour, and link to it here in the bug report) - -(If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version) +(If possible, please create an example project here on GitLab.com that exhibits the problematic +behavior, and link to it here in the bug report. +If you are using an older version of GitLab, this will also determine whether the bug has been fixed +in a more recent version) - -What is the current bug behavior? +## What is the current bug behavior? (What actually happens) - -What is the expected correct behavior? +## What is the expected correct behavior? (What you should see instead) +## Relevant logs and/or screenshots -Relevant logs and/or screenshots - -(Paste any relevant logs - please use code blocks (```) to format console output, -logs, and code as it's very hard to read otherwise.) - +(Paste any relevant logs - please use code blocks (```) to format console output, logs, and code, as +it's very hard to read otherwise.) -Possible fixes +## Possible fixes (If you can, link to the line of code that might be responsible for the problem) diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 49918b8f023..5c24ec6caf6 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# File Locking **(CORE)** +# File Locking **(FREE)** Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, @@ -26,7 +26,7 @@ GitLab supports two different modes of file locking: - [Exclusive file locks](#exclusive-file-locks) for binary files: done **through the command line** with Git LFS and `.gitattributes`, it prevents locked - files from being modified on any branch. **(CORE)** + files from being modified on any branch. **(FREE)** - [Default branch locks](#default-branch-file-and-directory-locks): done **through the GitLab UI**, it prevents locked files and directories being modified on the default branch. **(PREMIUM)** @@ -41,7 +41,7 @@ users will be prevented from modifying locked files by pushing, merging, or any other means, and will be shown an error like: `The path '.gitignore' is locked by Administrator`. -## Exclusive file locks +## Exclusive file locks **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. @@ -198,7 +198,8 @@ Suggested workflow for shared projects: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/). This process allows you to lock one file at a time through the GitLab UI and -requires access to [GitLab Premium, GitLab.com Silver](https://about.gitlab.com/pricing/), or higher tiers. +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`). diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md deleted file mode 100644 index 206013210a0..00000000000 --- a/doc/user/project/gpg_signed_commits/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../repository/gpg_signed_commits/index.md' ---- - -This document was moved to [another location](../repository/gpg_signed_commits/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 1d92e32e071..5ffc2878269 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -7,22 +7,28 @@ type: reference # Syntax Highlighting -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. -If GitLab is guessing wrong, you can override its choice of language using the `gitlab-language` attribute in `.gitattributes`. For example, if you are working in a Prolog project and using the `.pl` file extension (which would normally be highlighted as Perl), you can add the following to your `.gitattributes` file: +If GitLab is guessing wrong, you can override its choice of language using the +`gitlab-language` attribute in `.gitattributes`. For example, if you are working in a +<!-- vale gitlab.Spelling = NO --> Prolog <!-- vale gitlab.Spelling = YES --> +project and using the `.pl` file extension (which would normally be highlighted as Perl), +you can add the following to your `.gitattributes` file: ``` conf *.pl gitlab-language=prolog ``` -When you check in and push that change, all `*.pl` files in your project will be highlighted as Prolog. +<!-- vale gitlab.Spelling = NO --> +When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. +<!-- vale gitlab.Spelling = YES --> -The paths here are simply Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: ``` conf /Nicefile gitlab-language=ruby @@ -38,7 +44,8 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen /other-file gitlab-language=text?token=Error ``` -Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). +Please note that these configurations only take effect when the `.gitattributes` +file is in your default branch (usually `master`). 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/import/cvs.md b/doc/user/project/import/cvs.md index 82ff889c043..61d4d29aa4d 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -62,7 +62,7 @@ Migrating to Git/GitLab will benefit you: an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. - **Support for many network protocols**. Git supports SSH, HTTP/HTTPS and rsync - among others, whereas CVS supports only SSH and its own insecure pserver + among others, whereas CVS supports only SSH and its own insecure `pserver` protocol with no user authentication. ## How to migrate @@ -70,7 +70,7 @@ Migrating to Git/GitLab will benefit you: Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) -- [Stack Overflow post on importing the CVS repo](https://stackoverflow.com/a/11490134/974710) +- [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) - [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 38679914a9d..bac10cb0948 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -29,7 +29,8 @@ If you want to continue monitoring your dependencies, see the ## What happened to my account? Your account has been automatically closed on May 15th, 2018. If you had a paid -subscription at that time, your card will be refunded on a pro rata temporis basis. +subscription at that time, your card will be refunded on a +<!-- vale gitlab.Spelling = NO --> pro rata temporis <!-- vale gitlab.Spelling = YES --> basis. You may contact `gemnasium@gitlab.com` regarding your closed account. ## Will my account/data be transferred to GitLab Inc.? @@ -66,15 +67,18 @@ GitHub.com or GitHub Enterprise repository. This will automatically prompt GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results back to both GitLab and GitHub when completed. -1. Create a new project, and select "CI/CD for external repo": +<!-- vale gitlab.Spelling = NO --> + +1. Create a new project, and select **CI/CD for external repo**: ![Create new Project](img/gemnasium/create_project_v13_5.png) + <!-- vale gitlab.Spelling = YES --> -1. Use the "GitHub" button to connect your repositories. +1. Use the **GitHub** button to connect your repositories. ![Connect from GitHub](img/gemnasium/connect_github_v13_5.png) -1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". +1. Select the project(s) to be set up with GitLab CI/CD and choose **Connect**. ![Select projects](img/gemnasium/select_project_v13_5.png) diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 0e8cc159aec..3ff612c51a7 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,11 +9,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -1. From your GitLab dashboard click **New project** -1. Switch to the **Import project** tab -1. Click on the **Repo by URL** button -1. Fill in the "Git repository URL" and the remaining project fields -1. Click **Create project** to begin the import process -1. Once complete, you will be redirected to your newly created project +<!-- vale gitlab.Spelling = NO --> +<!-- vale gitlab.SubstitutionWarning = NO --> + +1. From your GitLab dashboard click **New project**. +1. Switch to the **Import project** tab. +1. Click on the **Repo by URL** button. +1. Fill in the "Git repository URL" and the remaining project fields. +1. Click **Create project** to begin the import process. +1. Once complete, you will be redirected to your newly created project. + +<!-- vale gitlab.Spelling = YES --> +<!-- vale gitlab.SubstitutionWarning = YES --> ![Import project by repository URL](img/import_projects_from_repo_url.png) diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 3642d07106c..a816dca59bc 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -30,7 +30,7 @@ There are two approaches to SVN to Git migration: migration. It creates a writable Git mirror of a local or remote Subversion repository and that way you can use both Subversion and Git as long as you like. It requires access to your GitLab server as it talks with the Git repositories -directly in a filesystem level. +directly in a file system level. ### SubGit prerequisites diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md deleted file mode 100644 index 31f9b200558..00000000000 --- a/doc/user/project/import/tfs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'tfvc.md' ---- - -This document was moved to [another location](tfvc.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/index.md b/doc/user/project/index.md index e3079c3731d..607049b512e 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -17,12 +17,12 @@ the number of private projects you create. ## Project features -When you create a project in GitLab, you'll have access to a large number of +When you create a project in GitLab, you receive access to a large number of [features](https://about.gitlab.com/features/): **Repositories:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues +- [Issue tracker](issues/index.md): Discuss implementations with your team in issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Repositories](repository/index.md): Host your code in a fully @@ -42,13 +42,13 @@ When you create a project in GitLab, you'll have access to a large number of **Issues and merge requests:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues +- [Issue tracker](issues/index.md): Discuss implementations with your team in issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before - implementing a change **(STARTER)** + implementing a change - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): Your Git diff tool right from the GitLab UI - [Review Apps](../../ci/review_apps/index.md): Live preview the results @@ -108,7 +108,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. - [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. -- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** +- [Code owners](code_owners.md): specify code owners for certain files - [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** - [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)** @@ -192,7 +192,7 @@ To delete a project, first navigate to the home page for that project. 1. Click **Delete project** 1. Confirm this action by typing in the expected text. -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). ## CI/CD for external repositories **(PREMIUM)** @@ -214,11 +214,11 @@ filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, ### Leave a project -**Leave project** will only display on the project's dashboard +**Leave project** only displays on the project's dashboard when a project is part of a group (under a [group namespace](../group/index.md#namespaces)). -If you choose to leave a project you will no longer be a project -member, therefore, unable to contribute. +If you choose to leave a project you are no longer a project +member, and cannot contribute. ## Project's landing page @@ -230,15 +230,15 @@ with [permissions to view the project's code](../permissions.md#project-members- - The content of a [`README` or an index file](repository/#repository-readme-and-index-files) - is displayed (if any), followed by the list of directories within the + 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 - visitor will see the list of files and directories of the repository. + visitor sees the list of files and directories of the repository. -For users without permissions to view the project's code: +For users without permissions to view the project's code, GitLab displays: -- The wiki homepage is displayed, if any. -- The list of issues within the project is displayed. +- The wiki homepage, if any. +- The list of issues in the project. ## GitLab Workflow - VS Code extension @@ -259,15 +259,15 @@ Depending on the situation, different things apply. When [renaming a user](../profile/index.md#changing-your-username), [changing a group path](../group/index.md#changing-a-groups-path) or [renaming a repository](settings/index.md#renaming-a-repository): -- Existing web URLs for the namespace and anything under it (e.g., projects) will +- 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 will redirect to the new remote URL. Every time you push/pull to a + 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 will be displayed instead of rejecting your action. - This means that any automation scripts, or Git clients will continue to + 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. -- The redirects will be available as long as the original path is not claimed by +- The redirects are available as long as the original path is not claimed by another group, user or project. ## Use your project as a Go package @@ -278,11 +278,11 @@ and `godoc.org` discovery requests, including the [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. Private projects, including projects in subgroups, can be used as a Go package, -but may require configuration to work correctly. GitLab will respond correctly +but may require configuration to work correctly. GitLab responds correctly to `go get` discovery requests for projects that *are not* in subgroups, regardless of authentication or authorization. [Authentication](#authenticate-go-requests) is required to use a private project -in a subgroup as a Go package. Otherwise, GitLab will truncate the path for +in a subgroup as a Go package. Otherwise, GitLab truncates the path for private projects in subgroups to the first two segments, causing `go get` to fail. @@ -302,10 +302,10 @@ queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) `GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go modules and Go module prefixes. For example, -`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that -one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all* -projects on GitLab.com. Go will not query module proxies if the module name or a -prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum +`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that +one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* +projects on GitLab.com. Go does not query module proxies if the module name or a +prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum databases if the module name or a prefix of it appears in `GONOPRIVATE` or `GONOSUMDB`. @@ -315,8 +315,8 @@ To authenticate requests to private projects made by Go, use a [`.netrc` file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access token](../profile/personal_access_tokens.md) in the password field. **This only works if your GitLab instance can be accessed with HTTPS.** The `go` command -will not transmit credentials over insecure connections. This will authenticate -all HTTPS requests made directly by Go but will not authenticate requests made +does not transmit credentials over insecure connections. This authenticates +all HTTPS requests made directly by Go, but does not authenticate requests made through Git. For example: @@ -332,16 +332,18 @@ On Windows, Go reads `~/_netrc` instead of `~/.netrc`. ### Authenticate Git fetches -If a module cannot be fetched from a proxy, Go will fall back to using Git (for -GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively, -Git can be configured to embed specific credentials in the request URL, or to -use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories): +If a module cannot be fetched from a proxy, Go falls back to using Git (for +GitLab projects). Git uses `.netrc` to authenticate requests. You can also +configure Git to either: + +- Embed specific credentials in the request URL. +- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. ```shell -# embed credentials in any request to GitLab.com: +# Embed credentials in any request to GitLab.com: git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" -# use SSH instead of HTTPS: +# Use SSH instead of HTTPS: git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" ``` @@ -352,9 +354,9 @@ git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.examp To quickly access a project from the GitLab UI using the project ID, visit the `/projects/:id` URL in your browser or other tool accessing the project. -## Project aliases **(PREMIUM ONLY)** +## Project aliases **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. When migrating repositories to GitLab and they are being accessed by other systems, it's very useful to be able to access them using the same name especially when @@ -369,12 +371,12 @@ A project alias can be only created via API and only by GitLab administrators. Follow the [Project Aliases API documentation](../../api/project_aliases.md) for more details. -Once an alias has been created for a project (e.g., an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned -using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of +After an alias has been created for a project (such as an alias `gitlab` for the +project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository +with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`). -## Project activity analytics overview **(ULTIMATE ONLY)** +## Project activity analytics overview **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 434ae760aff..d63599d02bc 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,7 +4,7 @@ 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 --- -# IBM Engineering Workflow Management (EWM) Integration **(CORE)** +# IBM Engineering Workflow Management (EWM) Integration **(FREE)** This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md deleted file mode 100644 index 1fbbee36173..00000000000 --- a/doc/user/project/integrations/generic_alerts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/generic_alerts.md' ---- - -This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index ccf4b6cb303..ef8c9d59132 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,7 +4,7 @@ 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 --- -# GitLab Slack application **(FREE ONLY)** +# GitLab Slack application **(FREE SAAS)** > - Introduced in GitLab 9.4. > - Distributed to Slack App Directory in GitLab 10.2. diff --git a/doc/user/project/integrations/img/mattermost_configuration.png b/doc/user/project/integrations/img/mattermost_configuration.png Binary files differdeleted file mode 100644 index 18c0036846d..00000000000 --- a/doc/user/project/integrations/img/mattermost_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_configuration_v2.png b/doc/user/project/integrations/img/mattermost_configuration_v2.png Binary files differnew file mode 100644 index 00000000000..e05b34fd77a --- /dev/null +++ b/doc/user/project/integrations/img/mattermost_configuration_v2.png diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 8dd7e4309b4..58f7ea3279f 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -10,7 +10,7 @@ GitLab provides a way to push update messages to an Irker server. When configured, pushes to a project trigger the service to send data directly to the Irker server. -See the project homepage for further information: <https://gitlab.com/esr/irker> +See the [project homepage](https://gitlab.com/esr/irker) for further information. ## Needed setup diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 306a16bd873..aa5d11282d9 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,57 +6,82 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Jira integration -If you need to use Jira to track work that's implemented in GitLab, Jira integrations with GitLab make the process of working across systems more efficient. +You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the +process of working across these systems more efficient. -This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). +The GitLab Jira integration, available in every GitLab project by default, allows you to connect +to any Jira instance, whether on Atlassian cloud or self-managed. -After you set up this integration, you can cross-reference activity in the GitLab project with any of your projects in Jira. This includes the ability to close or transition Jira issues when work is completed in GitLab. +You can also install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). +For more information about the differences between the two integrations, see +[Jira integrations](jira_integrations.md). -Features include: +After you set up this integration, you can cross-reference activity in the GitLab project with any +of your projects in Jira. This includes the ability to close or transition Jira issues when work is +completed in GitLab and: -- **Mention a Jira issue ID** in a commit message or MR (merge request) and +- Mention a Jira issue ID in a commit message or MR (merge request) and: - GitLab links to the Jira issue. - The Jira issue adds a comment with details and a link back to the activity in GitLab. -- **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: +- Mention that a commit or MR resolves or closes a specific Jira issue and when it's merged to the default branch: - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. -- **View a list of Jira issues directly in GitLab** **(PREMIUM)** +- Run a pipeline on an MR linked to a Jira issue: + - The Jira issue shows the current pipeline status (in the sidebar as "builds"). +- Deploy to an environment from an MR linked to a Jira issue: + - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). +- Create or modify a feature flag that mentions a Jira issue in its description: + - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). +- View a list of Jira issues directly in GitLab **(PREMIUM)** -For additional features, you can install the -[Jira Development Panel integration](../../../integration/jira_development_panel.md). -This enables you to: +Additional features provided by the Jira Development Panel integration include: - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. - Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. - -See the [feature comparison](jira_integrations.md#feature-comparison) for more details. +- Showing pipeline, deployment, and feature flags in Jira issues. ## Configuration <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). -Each GitLab project can be configured to connect to an entire Jira instance. That -means one GitLab project can interact with _all_ Jira projects in that instance, once -configured. Therefore, you do not have to explicitly associate -a GitLab project with any single Jira project. +Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab +project can interact with _all_ Jira projects in that instance, once configured. For: + +- The [view Jira issues](#view-jira-issues) feature, you must associate a GitLab project with a + specific Jira project. +- Other features, you do not have to explicitly associate a GitLab project with any single Jira + project. + +If you have one Jira instance, you can pre-fill the settings. For more information, see the +documentation for: + +- [Project integration management](../../admin_area/settings/project_integration_management.md). +- [Services Templates](services_templates.md). + +To enable the Jira service in GitLab, you must: -If you have one Jira instance, you can pre-fill the settings page with a default -template. See the [Services Templates](services_templates.md) docs. +1. Configure the project in Jira. +1. Enter the correct values in GitLab. -In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab. +### Configure Jira -### Configuring Jira +The process for configuring Jira depends on whether you host Jira on your own server or on +[Atlassian cloud](https://www.atlassian.com/cloud). #### Jira Server -**Jira Server** supports basic authentication. When connecting, a **username and password** are required. Note that connecting to Jira Server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). +Jira Server supports basic authentication. When connecting, a **username and password** are +required. Connecting to Jira Server via CAS is not possible. For more information, see +[set up a user in Jira Server](jira_server_configuration.md). -#### Jira Cloud +#### Jira on Atlassian cloud -**Jira Cloud** supports authentication through an API token. When connecting to **Jira Cloud**, an **email and API token** are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). +Jira on Atlassian cloud supports authentication through an API token. When connecting to Jira on +Atlassian cloud, an **email and API token** are required. For more information, see +[set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). -### Configuring GitLab +### Configure GitLab > **Notes:** > @@ -79,10 +104,10 @@ Enter the further details on the page as described in the following table. | Field | Description | | ----- | ----------- | -| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | -| `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. | -| `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | +| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | +| `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | +| `Password/API token` |Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | | `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** @@ -107,19 +132,19 @@ administration UI. You can get the ID you need in either of the following ways: 1. By mousing over the link for the transition you want and looking for the "action" parameter in the URL -Note that the transition ID may vary between workflows (e.g., bug vs. story), +Note that the transition ID may vary between workflows (for example, bug vs. story), even if the status you are changing to is the same. #### Disabling comments on Jira issues You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. -See the [Configuring GitLab](#configuring-gitlab) section and uncheck the **Enable comments** setting. +See the [Configure GitLab](#configure-gitlab) section and uncheck the **Enable comments** setting. ## Jira issues -By now you should have [configured Jira](#configuring-jira) and enabled the -[Jira service in GitLab](#configuring-gitlab). If everything is set up correctly +By now you should have [configured Jira](#configure-jira) and enabled the +[Jira service in GitLab](#configure-gitlab). If everything is set up correctly you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. @@ -201,7 +226,7 @@ with a link to the commit that resolved the issue. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configuring-gitlab) in GitLab by an administrator. +You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configure-gitlab) in GitLab by an administrator. ![Jira issues integration enabled](img/jira/open_jira_issues_list_v13.2.png) diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index b8eebef8e42..e9f30f32308 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -4,10 +4,10 @@ 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 --- -# Creating an API token in Jira Cloud +# Create an API token in Jira on Atlassian cloud -An API token is needed when integrating with Jira Cloud, follow the steps -below to create one: +For [integrations with Jira](jira.md), an API token is needed when integrating with Jira +on Atlassian cloud. To create an API token: 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. @@ -17,10 +17,11 @@ below to create one: 1. Click **Create API token**. -![Jira API token](img/jira_api_token_menu.png) + ![Jira API token](img/jira_api_token_menu.png) -![Jira API token](img/jira_api_token.png) +1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configure-gitlab). -1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab). + ![Jira API token](img/jira_api_token.png) -The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section. +The Jira configuration is complete. You need the newly created token, and the associated email +address, when [configuring GitLab](jira.md#configure-gitlab). diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 3c91fd3549f..3daea250aac 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -6,26 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jira integrations -## Introduction +GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). -GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with -extensive, established data and business processes they rely on. +[Issues](../issues/index.md) are a tool for discussing ideas, and planning and tracking work. +However, your organization may already use Jira for these purposes, with extensive, established data +and business processes they rely on. -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using the GitLab Jira integrations. +Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work +exclusively in GitLab, you can also continue to use Jira by using the GitLab Jira integrations. -## Integrations +## Integration types -The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features: +There are two different Jira integrations that allow different types of cross-referencing between +GitLab activity and Jira issues, with additional features: -- [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. -- [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace. - - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). - - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). +- [Jira integration](jira.md), built in to GitLab. In a given GitLab project, it can be configured + to connect to any Jira instance, either hosted by you or hosted in + [Atlassian cloud](https://www.atlassian.com/cloud). +- [Jira development panel integration](../../../integration/jira_development_panel.md). Connects all + GitLab projects under a specified group or personal namespace. -### Feature comparison +Jira development panel integration configuration depends on whether: + +- You're using GitLab.com or a self-managed GitLab instance. +- You're using Jira on [Atlassian cloud](https://www.atlassian.com/cloud) or on your own server. + +| You use Jira on: | For the Jira development panel integration, GitLab.com customers need: | For the Jira development panel integration, GitLab self-managed customers need: | +|:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Atlassian cloud | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268278) for more information. | +| Your own server | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | + +NOTE: +DVCS means distributed version control system. + +## Feature comparison + +The integration to use depends on the capabilities your require. You can install both at the same +time. | Capability | Jira integration | Jira Development Panel integration | -|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +|:----------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| | Mention of Jira issue ID in GitLab is automatically linked to that issue | Yes | No | | Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | | Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index d2a42c0535e..5bb17388a1e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -4,61 +4,65 @@ 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 --- -# Creating a username and password for Jira Server +# Create Jira Server username and password -We need to create a user in Jira to have access to all projects that need to integrate with GitLab. +For [integrations with Jira](jira.md), you must create a user account in Jira to have access to +all projects that need to integrate with GitLab. -As an example, we create a user named `gitlab` and add it to a new group -named `gitlab-developers`. +The Jira user account created for the integration must have write access to +your Jira projects. -NOTE: -It is important that the Jira user created for the integration is given 'write' -access to your Jira projects. This is covered in the process below. +As an example, the following process creates a user named `gitlab` and that's a +member of a new group named `gitlab-developers`: -1. Log in to your Jira instance as an administrator and under **Jira Administration** - go to **User Management** to create a new user. +1. Sign in to your Jira instance as an administrator, and + then go to the gear icon and select **User Management**. ![Jira user management link](img/jira_user_management_link.png) -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in Jira. Enter the user's name and a _valid_ e-mail address - since Jira sends a verification e-mail to set up the password. +1. Create a new user account (for example, `gitlab`) with write access to + projects in Jira. Enter the user account's name and a valid e-mail address, + because Jira sends a verification email to set up the password. - Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You - need to create an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password. + Jira creates the username by using the email prefix. You can change the + username later, if needed. The GitLab integration doesn't support SSO (such + as SAML). You need to create an HTTP basic authentication password. You can + do this by visiting the user profile, looking up the username, and setting a + password. ![Jira create new user](img/jira_create_new_user.png) -1. Create a `gitlab-developers` group (we give this group write access to Jira - projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**. +1. From the sidebar, select **Groups**. ![Jira create new user](img/jira_create_new_group.png) - Give it a name and click **Add group**. +1. In the **Add group** section, enter a **Name** for the group (for example, + `gitlab-developers`), and then select **Add group**. -1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a selected group. - Under **Add members to selected group(s)**, enter `gitlab`. +1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a + selected group. In the **Add members to selected group(s)** area, enter `gitlab`. ![Jira add user to group](img/jira_add_user_to_group.png) - Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. - This membership is saved automatically. + Select **Add selected users**, and `gitlab` should appear in the **Group member(s)** + area. This membership is saved automatically. ![Jira added user to group](img/jira_added_user_to_group.png) -1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. - To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. - Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. +1. To give the newly-created group 'write' access, you must create a permission + scheme. To do this, in the admin menu, go to the gear icon and select **Issues**. -1. Once your permission scheme is created, you are taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, - click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` - from the dropdown. +1. From the sidebar, select **Permission Schemes**. + +1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a + **Description**, and then select **Add**. + +1. In the permissions scheme list, locate your new permissions scheme, and + select **Permissions**. Next to **Administer Projects**, select **Edit**. In + the **Group** list, select `gitlab-developers`. ![Jira group access](img/jira_group_access.png) The Jira configuration is complete. Write down the new Jira username and its -password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password, as you need them when [configuring GitLab](jira.md#configure-gitlab). diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md deleted file mode 100644 index 646c9ed66d5..00000000000 --- a/doc/user/project/integrations/kubernetes.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../clusters/index.md' ---- - -This document was moved to [another location](../clusters/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index e80f672d05d..db190f47b01 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -58,5 +58,7 @@ At the end, fill in your Mattermost details: | **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | +| **Branches to be notified** | Select which types of branches to send notifications for. | +| **Labels to be notified** | Optional labels that the issue or merge request must have in order to trigger a notification. Leave blank to get all notifications. | -![Mattermost configuration](img/mattermost_configuration.png) +![Mattermost configuration](img/mattermost_configuration_v2.png) diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index c391877be20..840f46be97b 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -39,7 +39,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | | Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/alert_integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | | [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | | [HipChat](hipchat.md) | Private group chat and IM | No | @@ -53,8 +53,8 @@ Click on the service links to see further configuration instructions and details | Packagist | Update your projects on Packagist, the main Composer repository | Yes | | Pipelines emails | Email the pipeline status to a list of recipients | No | | [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | -| [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | No | -| [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application | No | +| [Slack slash commands](slack_slash_commands.md) **(FREE SELF)** | Use slash commands in Slack to control GitLab | No | +| [GitLab Slack application](gitlab_slack_application.md) **(FREE SAAS)** | Use Slack's official application | No | | PivotalTracker | Project Management Software (Source Commits Endpoint) | No | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md deleted file mode 100644 index 69e2ea2856c..00000000000 --- a/doc/user/project/integrations/project_services.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'overview.md' ---- - -This document was moved to [Integrations](overview.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 959c4cc623b..d40c638105e 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -4,22 +4,25 @@ group: Health 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 --- -# Prometheus integration +# Prometheus integration **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. -GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly within GitLab. +GitLab offers powerful integration with [Prometheus](https://prometheus.io) for +monitoring key metrics of your apps, directly in GitLab. Metrics for each environment are retrieved from Prometheus, and then displayed -within the GitLab interface. +in the GitLab interface. ![Environment Dashboard](img/prometheus_dashboard.png) 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 other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). +- For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the +[metric library](prometheus_library/index.md). You can also +[add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -28,7 +31,8 @@ Once enabled, GitLab detects metrics from known services in the [metric library] > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. -GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. +GitLab can seamlessly deploy and manage Prometheus on a +[connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. #### Requirements @@ -36,7 +40,7 @@ GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cl #### Getting started -Once you have a connected Kubernetes cluster, deploying a managed Prometheus is as easy as a single click. +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 @@ -46,17 +50,28 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is #### 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 within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). +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, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +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) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. +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. +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 @@ -161,15 +176,16 @@ Installing and configuring Prometheus to monitor applications is fairly straight 1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 1. Set up one of the [supported monitoring targets](prometheus_library/index.md) -1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) +1. Configure the Prometheus server to + [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab +The actual configuration of Prometheus integration in GitLab requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), -additional information like Client ID and Service Account credentials can be passed which -GitLab can use to access the resource. More information about authentication from a +you can pass information like Client ID and Service Account credentials. +GitLab can use these to access the resource. More information about authentication from a service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). @@ -189,12 +205,13 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab, using the domain name or IP address of the Thanos server you'd like +with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). 1. Click the **Prometheus** service. -1. Provide the domain name or IP address of your server, for example `http://thanos.example.com/` or `http://192.0.2.1/`. +1. Provide the domain name or IP address of your server, for example + `http://thanos.example.com/` or `http://192.0.2.1/`. 1. Click **Save changes**. ### Precedence with multiple Prometheus configurations @@ -221,7 +238,7 @@ can use only one: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. > - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. -Developers can view the performance impact of their changes within the merge +Developers can view the performance impact of their changes in the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index b563dd34896..4a88010a343 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring AWS resources +# Monitoring AWS resources **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index c14c14658b7..290313ac1af 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring HAProxy +# Monitoring HAProxy **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 501e8ba7c1d..e10da8c6ebe 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Prometheus Metrics library +# Prometheus Metrics library **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ae330158a58..ed1949536a3 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring Kubernetes +# Monitoring Kubernetes **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md deleted file mode 100644 index a275efce5bb..00000000000 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 4cb827b3b4a..dcaef1e2ae6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring NGINX +# Monitoring NGINX **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index f7542ec78f7..f7e6b6e76d6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring NGINX Ingress Controller +# Monitoring NGINX Ingress Controller **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. 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 c855e564753..0c86c4921b3 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring NGINX Ingress Controller with VTS metrics +# Monitoring NGINX Ingress Controller with VTS metrics **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md deleted file mode 100644 index 0c2ce3002ee..00000000000 --- a/doc/user/project/integrations/prometheus_units.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/yaml_number_format.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/yaml_number_format.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 9e9f5b8297f..ab798675278 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -45,6 +45,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). 1. Select the **Notify only broken pipelines** check box to only notify on failures. 1. In the **Branches to be notified** select box, choose which types of branches to send notifications for. +1. Leave the **Labels to be notified** field blank to get all notifications or add labels that the issue or merge request must have in order to trigger a notification. 1. Click **Test settings and save changes**. Your Slack team now starts receiving GitLab event notifications as configured. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 1e4577fb88e..4f206cd3e45 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -4,7 +4,7 @@ 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 --- -# Slack slash commands **(CORE ONLY)** +# Slack slash commands **(FREE SELF)** > Introduced in GitLab 8.15. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 47a44e53b47..27c2cb08d10 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -31,7 +31,7 @@ update a backup mirror, or even deploy to your production server. Webhooks are available: -- Per project, at a project's **Settings > Webhooks** menu. **(CORE)** +- Per project, at a project's **Settings > Webhooks** menu. **(FREE)** - Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** NOTE: @@ -1151,10 +1151,15 @@ X-Gitlab-Event: Pipeline Hook "email": "admin@example.com" }, "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "is_shared":true + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "is_shared": true, + "tags": [ + "linux", + "docker", + "shared-runner" + ] }, "artifacts_file":{ "filename": null, @@ -1183,7 +1188,11 @@ X-Gitlab-Event: Pipeline Hook "id":380987, "description":"shared-runners-manager-6.gitlab.com", "active":true, - "is_shared":true + "is_shared":true, + "tags": [ + "linux", + "docker" + ] }, "artifacts_file":{ "filename": null, @@ -1209,10 +1218,14 @@ X-Gitlab-Event: Pipeline Hook "email": "admin@example.com" }, "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "is_shared":true + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "is_shared": true, + "tags": [ + "linux", + "docker" + ] }, "artifacts_file":{ "filename": null, @@ -1308,7 +1321,11 @@ X-Gitlab-Event: Job Hook "active": true, "is_shared": false, "id": 380987, - "description": "shared-runners-manager-6.gitlab.com" + "description": "shared-runners-manager-6.gitlab.com", + "tags": [ + "linux", + "docker" + ] } } ``` @@ -1468,6 +1485,74 @@ X-Gitlab-Event: Member Hook } ``` +### Subgroup events **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. + +Subgroup events are triggered when: + +- A [subgroup is created in a group](#subgroup-created-in-a-group) +- A [subgroup is removed from a group](#subgroup-removed-from-a-group) + +#### Subgroup created in a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Request Body**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_create", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +#### Subgroup removed from a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Request Body**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_destroy", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +NOTE: +Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transferring-groups) + ### Feature Flag events Triggered when a feature flag is turned on or off. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7119970fca0..d2f73a88eae 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards **(CORE)** +# Issue Boards **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). @@ -38,10 +38,9 @@ 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) | |------------------|--------------------------------|------------------------------|---------------------------|----------------| -| Core / Free | Multiple | 1 | No | No | -| Starter / Bronze | Multiple | 1 | Yes | No | -| Premium / Silver | Multiple | Multiple | Yes | Yes | -| Ultimate / Gold | Multiple | Multiple | Yes | Yes | +| 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. @@ -54,10 +53,10 @@ the Issue Board feature. ## Multiple issue boards > - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 12.1. > - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). -Multiple issue boards allow for more than one issue board for a given project **(CORE)** or group **(PREMIUM)**. +Multiple issue boards allow for more than one issue board for a given project **(FREE)** or group **(PREMIUM)**. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -228,7 +227,7 @@ and vice versa. ## GitLab Enterprise features for issue boards -GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some +GitLab issue boards are available on the GitLab Free tier, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). ### Configurable issue boards **(STARTER)** @@ -258,8 +257,8 @@ the Configurable Issue Board feature. ### Focus mode > - [Introduced]((https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep)) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab.com in 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab SaaS in 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Free self-managed in 13.0. To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. @@ -435,13 +434,13 @@ To remove a list from an issue board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -### Add issues to a list **(CORE ONLY)** +### Add issues to a list **(FREE SELF)** > - Feature flag [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47898) in GitLab 13.7. > - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. > - It's disabled on GitLab.com. > - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(FREE SELF)** You can add issues to a list in a project issue board by clicking the **Add issues** button in the top right corner of the issue board. This opens up a modal @@ -461,7 +460,7 @@ the list by filtering by the following: - Release - Weight -#### Enable or disable adding issues to the list **(CORE ONLY)** +#### Enable or disable adding issues to the list **(FREE SELF)** Adding issues to the list is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) @@ -563,7 +562,7 @@ another list. This makes it faster to reorder many issues at once. To select and move multiple cards: -1. Select each card with <kbd>Ctrl</kbd>+`Click` on Windows or Linux, or <kbd>Cmd</kbd>+`Click` on MacOS. +1. Select each card with <kbd>Control</kbd>+`Click` on Windows or Linux, or <kbd>Command</kbd>+`Click` on MacOS. 1. Drag one of the selected cards to another position or list and all selected cards are moved. ![Multi-select Issue Cards](img/issue_boards_multi_select_v12_4.png) diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md deleted file mode 100644 index 6fa2822aa9a..00000000000 --- a/doc/user/project/issues/automatic_issue_closing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#closing-issues-automatically' ---- - -This document was moved to [another location](managing_issues.md#closing-issues-automatically). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md deleted file mode 100644 index 45b905f2fb5..00000000000 --- a/doc/user/project/issues/closing_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#closing-issues' ---- - -This document was moved to [another location](managing_issues.md#closing-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md deleted file mode 100644 index 53648b53ea3..00000000000 --- a/doc/user/project/issues/create_new_issue.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#create-a-new-issue' ---- - -This document was moved to [another location](managing_issues.md#create-a-new-issue). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index e7cd1377603..4fa7bef4fb2 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Export Issues to CSV > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/releases/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). -> - Moved to GitLab Core in GitLab 12.10. +> - Moved to GitLab Free in GitLab 12.10. Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. @@ -20,7 +20,7 @@ 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) CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, -Open Office Calc, or Google Spreadsheets. +Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO --> or Google Spreadsheets. ## Use cases diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md deleted file mode 100644 index d8e1485a2dc..00000000000 --- a/doc/user/project/issues/deleting_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#deleting-issues' ---- - -This document was moved to [another location](managing_issues.md#deleting-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 3739070be01..8dc5c3396ae 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,14 +1,14 @@ --- -stage: Create -group: Knowledge +stage: Plan +group: Product Planning 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" --- -# Design Management **(CORE)** +# Design Management **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. -> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. +> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. Design Management allows you to upload design assets (wireframes, mockups, etc.) to GitLab issues and keep them stored in one single place, accessed by the Design @@ -46,7 +46,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u ## Supported files Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, -`gif`, `bmp`, `tiff`, `ico`, or `svg`. +`gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 34e9340067c..909a20f0e2f 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -41,7 +41,7 @@ You can see issues with their due dates in the [issues list](index.md#issues-lis Overdue issues have their icon and date colored red. To sort issues by their due dates, select **Due date** from the dropdown menu on the right. Issues are then sorted from the earliest due date to the latest. -To display isses with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). +To display issues with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). Due dates also appear in your [to-do list](../../todos.md). diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 74311eefd83..e398c6f86d0 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -4,35 +4,29 @@ 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 --- -# Issues **(CORE)** +# Issues **(FREE)** -Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. +Issues are the fundamental mechanism in GitLab to collaborate on ideas, solve +problems, and plan work. -## Overview +Using issues, you can share and discuss proposals (both before and during their +implementation) between you and your team, and outside collaborators. -The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, -and planning work. +You can use issues for many purposes, customized to your needs and workflow. +Common use cases include: -Issues can allow sharing and discussion of proposals before, and during, -their implementation between: +- Discussing the implementation of a new idea. +- Tracking tasks and work status. +- Accepting feature proposals, questions, support requests, or bug reports. +- Elaborating on new code implementations. -- You and your team. -- Outside collaborators. +For more information about using issues, see the +[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/) +GitLab blog post. -They can also be used for a variety of other purposes, customized to your -needs and workflow. - -Issues are always associated with a specific project. If you have multiple projects in a group, -you can view all of the issues collectively at the group level. - -**Common use cases include:** - -- Discussing the implementation of a new idea -- Tracking tasks and work status -- Accepting feature proposals, questions, support requests, or bug reports -- Elaborating on new code implementations - -See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). +Issues are always associated with a specific project. If you have multiple +projects in a group, you can view all of the issues collectively at the group +level. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and @@ -41,63 +35,30 @@ To learn how our Strategic Marketing department uses GitLab issues with [labels] ## Parts of an issue -Issues contain a variety of content and metadata, enabling a large range of flexibility -in how they are used. Each issue can contain the following attributes, though not all items -must be set. - -<table class="borderless-table fixed-table"> -<tr> - <td> - <ul> - <li>Content</li> - <ul> - <li>Title</li> - <li>Description and tasks</li> - <li>Comments and other activity</li> - </ul> - <li>People</li> - <ul> - <li>Author</li> - <li>Assignee(s)</li> - </ul> - <li>State</li> - <ul> - <li>State (open or closed)</li> - <li>Health status (on track, needs attention, or at risk)</li> - <li>Confidentiality</li> - <li>Tasks (completed vs. outstanding)</li> - </ul> - </ul> - </td> - <td> - <ul> - <li>Planning and tracking</li> - <ul> - <li>Milestone</li> - <li>Due date</li> - <li>Weight</li> - <li>Time tracking</li> - <li>Labels</li> - <li>Votes</li> - <li>Reaction emoji</li> - <li>Linked issues</li> - <li>Assigned epic</li> - <li>Unique issue number and URL</li> - </ul> - </ul> - </td> -</tr> -</table> - -## Viewing and managing issues - -While you can view and manage details of an issue on the [issue page](#issue-page), -you can also work with multiple issues at a time using: - -- [Issues List](#issues-list). -- [Issue Boards](#issue-boards). -- Issue references. -- [Epics](#epics) **(PREMIUM)**. +Issues have a flexible content and metadata structure. Here are some of the +elements you can provide in an issue: + +- Title +- Description and tasks +- Comments and other activity +- Author +- Assignees +- State (open or closed) +- Health status (on track, needs attention, or at risk) +- Confidentiality +- Tasks (completed vs. outstanding) +- Milestone +- Due date +- Weight +- Time tracking +- Labels +- Votes +- Reaction emoji +- Linked issues +- Assigned epic +- Unique issue number and URL + +## View and manage issues Key actions for issues include: @@ -105,7 +66,17 @@ Key actions for issues include: - [Moving issues](managing_issues.md#moving-issues) - [Closing issues](managing_issues.md#closing-issues) - [Deleting issues](managing_issues.md#deleting-issues) -- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) **(PREMIUM)** +- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) + +Although you can view and manage details of an issue on the [issue page](#issue-page), +you can also work with several issues at a time by using these features: + +- [Issues List](#issues-list): View a list of issues in a project or group. +- [Issue Boards](../issue_board.md): Organize issues with a project management + workflow for a feature or product release. +- Issue references +- [Epics](../../group/epics/index.md): Manage your portfolio of projects by + tracking groups of issues with a shared theme. ### Issue page @@ -114,18 +85,18 @@ Key actions for issues include: On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), and modify them if you have the necessary [permissions](../../permissions.md). -#### Real-time sidebar **(CORE ONLY)** +#### Real-time sidebar **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). +To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). ### Issues List ![Project Issues List view](img/project_issues_list_view.png) -On the Issues List, you can: +In the Issues List, you can: - View all issues in a project when opening the Issues List from a project context. - View all issues in a groups's projects when opening the Issues List from a group context. @@ -137,20 +108,22 @@ view, you can also make certain changes [in bulk](../bulk_editing.md) to the dis For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page for a rundown of all the fields and information in an issue. -You can sort a list of issues in several ways, for example by issue creation date, milestone due date. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page. +You can sort a list of issues in several ways, for example by issue creation date, milestone due date. +For more information, see the [Sorting and ordering issue lists](sorting_issue_lists.md) page. -### Issue boards +#### Cached issue count -![Issue board](img/issue_board.png) +> - [Introduced]([link-to-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/243753)) 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 this feature in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cached-issue-count) **(FREE SELF)** -[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their -labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using -highly customizable workflows. +WARNING: +This feature might not be available to you. Check the **version history** note above for details. -You can reorder issues in the column. If you drag an issue card to another column, its -associated label or assignee is changed to match that of the new column. The entire -board can also be filtered to only include issues from a certain milestone or an overarching -label. +In a group, the sidebar displays the total count of open issues and this value is cached if higher +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. ### Design Management @@ -158,12 +131,6 @@ With [Design Management](design_management.md), you can upload design assets to issues and view them all together for sharing and collaboration with your team. -### Epics **(PREMIUM)** - -[Epics](../../group/epics/index.md) let you manage your portfolio of projects more -efficiently and with less effort. Epics track groups of issues that share a theme, across -projects and milestones. - ### Related issues You can mark two issues as related, so that when viewing one, the other is always @@ -226,3 +193,22 @@ You can then see issue statuses in the [issue list](#issues-list) and the - [Issues API](../../../api/issues.md) - Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, Bugzilla, or EWM. + +## Enable or disable cached issue count **(FREE SELF)** + +Cached issue count in the left sidebar 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(:cached_sidebar_open_issues_count) +``` + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_open_issues_count) +``` diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 4c8630581f5..5218bb57bca 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed. ### Labels Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [GitLab Issue Board](index.md#issue-boards). +and they enable you to work with the [GitLab Issue Board](../issue_board.md). Group Labels, which allow you to use the same labels for all projects in the same group, can also be given to issues. They work exactly the same, but are immediately @@ -291,7 +291,7 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g After you write a comment, you can: -- Click **Comment** and to publish your comment. +- Click **Comment** to publish your comment. - Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) in that issue's main thread to discuss specific points. This invites other participants to reply directly to your thread, keeping related comments grouped together. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ef860df054e..7ca0556dff4 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -270,7 +270,7 @@ 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. -#### Customizing the issue closing pattern **(CORE ONLY)** +#### Customizing the issue closing pattern **(FREE SELF)** In order to change the default issue closing pattern, GitLab administrators must edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md deleted file mode 100644 index 3b40affcdc3..00000000000 --- a/doc/user/project/issues/moving_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#moving-issues' ---- - -This document was moved to [another location](managing_issues.md#moving-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 82b2d4fde52..91c26d49532 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,10 +4,10 @@ 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 --- -# Related issues **(CORE)** +# Related issues **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. -> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. +> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. Related issues are a bi-directional relationship between any two issues and appear in a block below the issue description. Issues can be across groups diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md deleted file mode 100644 index 79a50d5f812..00000000000 --- a/doc/user/project/issues/similar_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md#similar-issues' ---- - -This document was moved to [another location](index.md#similar-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index b4cb1c383ba..3a393b18579 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sorting and ordering issue lists **(CORE)** +# Sorting and ordering issue lists **(FREE)** You can sort a list of issues several ways, including by: diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md deleted file mode 100644 index 5bfa08de2ed..00000000000 --- a/doc/user/project/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/members/img/access_requests_management_13_8.png b/doc/user/project/members/img/access_requests_management_13_8.png Binary files differdeleted file mode 100644 index 950ef4dec01..00000000000 --- a/doc/user/project/members/img/access_requests_management_13_8.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..b7883e9d134 --- /dev/null +++ b/doc/user/project/members/img/access_requests_management_v13_9.png diff --git a/doc/user/project/members/img/add_user_email_accept_13_8.png b/doc/user/project/members/img/add_user_email_accept_13_8.png Binary files differdeleted file mode 100644 index ed980036af5..00000000000 --- a/doc/user/project/members/img/add_user_email_accept_13_8.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 differnew file mode 100644 index 00000000000..a6b303e05ca --- /dev/null +++ b/doc/user/project/members/img/add_user_email_accept_v13_9.png diff --git a/doc/user/project/members/img/add_user_email_ready_13_8.png b/doc/user/project/members/img/add_user_email_ready_v13_8.png Binary files differindex a610b46a176..a610b46a176 100644 --- a/doc/user/project/members/img/add_user_email_ready_13_8.png +++ b/doc/user/project/members/img/add_user_email_ready_v13_8.png diff --git a/doc/user/project/members/img/add_user_email_search_13_8.png b/doc/user/project/members/img/add_user_email_search_v13_8.png Binary files differindex 934cf19bd3d..934cf19bd3d 100644 --- a/doc/user/project/members/img/add_user_email_search_13_8.png +++ b/doc/user/project/members/img/add_user_email_search_v13_8.png diff --git a/doc/user/project/members/img/add_user_give_permissions_13_8.png b/doc/user/project/members/img/add_user_give_permissions_v13_8.png Binary files differindex 1916d056a52..1916d056a52 100644 --- a/doc/user/project/members/img/add_user_give_permissions_13_8.png +++ b/doc/user/project/members/img/add_user_give_permissions_v13_8.png diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png Binary files differindex a6dddec3fb7..a6dddec3fb7 100644 --- a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png +++ b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png diff --git a/doc/user/project/members/img/add_user_imported_members_13_8.png b/doc/user/project/members/img/add_user_imported_members_13_8.png Binary files differdeleted file mode 100644 index 725e447604f..00000000000 --- a/doc/user/project/members/img/add_user_imported_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_imported_members_v13_9.png b/doc/user/project/members/img/add_user_imported_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..e40240df2b2 --- /dev/null +++ b/doc/user/project/members/img/add_user_imported_members_v13_9.png diff --git a/doc/user/project/members/img/add_user_list_members_13_8.png b/doc/user/project/members/img/add_user_list_members_13_8.png Binary files differdeleted file mode 100644 index b8c0160c6d8..00000000000 --- a/doc/user/project/members/img/add_user_list_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_list_members_v13_9.png b/doc/user/project/members/img/add_user_list_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..7a07ea01d14 --- /dev/null +++ b/doc/user/project/members/img/add_user_list_members_v13_9.png diff --git a/doc/user/project/members/img/add_user_search_people_13_8.png b/doc/user/project/members/img/add_user_search_people_v13_8.png Binary files differindex e9aa58512ab..e9aa58512ab 100644 --- a/doc/user/project/members/img/add_user_search_people_13_8.png +++ b/doc/user/project/members/img/add_user_search_people_v13_8.png diff --git a/doc/user/project/members/img/project_groups_tab_13_8.png b/doc/user/project/members/img/project_groups_tab_13_8.png Binary files differdeleted file mode 100644 index 5d7948f0761..00000000000 --- a/doc/user/project/members/img/project_groups_tab_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_groups_tab_v13_9.png b/doc/user/project/members/img/project_groups_tab_v13_9.png Binary files differnew file mode 100644 index 00000000000..d1b6a640341 --- /dev/null +++ b/doc/user/project/members/img/project_groups_tab_v13_9.png diff --git a/doc/user/project/members/img/project_members_13_8.png b/doc/user/project/members/img/project_members_13_8.png Binary files differdeleted file mode 100644 index 9120d471b3b..00000000000 --- a/doc/user/project/members/img/project_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_direct_v13_9.png b/doc/user/project/members/img/project_members_filter_direct_v13_9.png Binary files differnew file mode 100644 index 00000000000..50115ee4052 --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_direct_v13_9.png diff --git a/doc/user/project/members/img/project_members_filter_inherited_v13_9.png b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png Binary files differnew file mode 100644 index 00000000000..433003fe58b --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png diff --git a/doc/user/project/members/img/project_members_search_v13_9.png b/doc/user/project/members/img/project_members_search_v13_9.png Binary files differnew file mode 100644 index 00000000000..67280d11dca --- /dev/null +++ b/doc/user/project/members/img/project_members_search_v13_9.png diff --git a/doc/user/project/members/img/project_members_sort_v13_9.png b/doc/user/project/members/img/project_members_sort_v13_9.png Binary files differnew file mode 100644 index 00000000000..47abe18ba49 --- /dev/null +++ b/doc/user/project/members/img/project_members_sort_v13_9.png diff --git a/doc/user/project/members/img/project_members_v13_9.png b/doc/user/project/members/img/project_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..3b48c752c6a --- /dev/null +++ b/doc/user/project/members/img/project_members_v13_9.png diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png Binary files differdeleted file mode 100644 index 6cbbb386396..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png Binary files differnew file mode 100644 index 00000000000..99be996c03e --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index cccb998fc31..00474098487 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -21,42 +21,74 @@ project's **Members**. When your project belongs to the group, group members inherit the membership and permission level for the project from the group. -![Project members page](img/project_members_13_8.png) +![Project members page](img/project_members_v13_9.png) From the image above, we can deduce the following things: - 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. -- For User1 there is no indication of a group, therefore they belong directly +- 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. -[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/21727), you can filter this list -using the dropdown on the right side: +## Filter and sort members -![Project members filter](img/project_members_filter_v12_6.png) +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. +> - Improvements are [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Improvements are enabled on GitLab.com. +> - Improvements are recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-project-member-management). **(FREE SELF)** -- **Show only direct members** displays only User1. -- **Show only inherited members** displays User0 and Administrator. +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. + +#### Display inherited members + +To display inherited members, include `Membership` `=` `Inherited` in the search text box. + +![Project members filter inherited](img/project_members_filter_inherited_v13_9.png) + +#### Display direct members + +To display direct members, include `Membership` `=` `Direct` in the search text box. + +![Project members filter direct](img/project_members_filter_direct_v13_9.png) + +### Search + +You can search for members by name, username, or email. + +![Project members search](img/project_members_search_v13_9.png) + +### Sort + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. + +![Project members sort](img/project_members_sort_v13_9.png) ## Add a user Right next to **People**, start typing the name or username of the user you want to add. -![Search for people](img/add_user_search_people_13_8.png) +![Search for people](img/add_user_search_people_v13_8.png) Select the user and the [permission level](../../permissions.md) that you'd like to give the user. Note that you can select more than one user. -![Give user permissions](img/add_user_give_permissions_13_8.png) +![Give user permissions](img/add_user_give_permissions_v13_8.png) Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above. -![List members](img/add_user_list_members_13_8.png) +![List members](img/add_user_list_members_v13_9.png) From there on, you can either remove an existing user or change their access level to the project. @@ -68,14 +100,14 @@ You can import another project's users in your own project by hitting the In the dropdown menu, you can see only the projects you are Maintainer on. -![Import members from another project](img/add_user_import_members_from_another_project_13_8.png) +![Import members from another project](img/add_user_import_members_from_another_project_v13_8.png) Select the one you want and hit **Import project members**. A flash message displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. -![Members list of new members](img/add_user_imported_members_13_8.png) +![Members list of new members](img/add_user_imported_members_v13_9.png) ## Invite people using their e-mail address @@ -83,18 +115,18 @@ 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. -![Invite user by mail](img/add_user_email_search_13_8.png) +![Invite user by mail](img/add_user_email_search_v13_8.png) As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project. -![Invite user by mail ready to submit](img/add_user_email_ready_13_8.png) +![Invite user by mail ready to submit](img/add_user_email_ready_v13_8.png) 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. -![Invite user members list](img/add_user_email_accept_13_8.png) +![Invite user members list](img/add_user_email_accept_v13_9.png) While unaccepted, the system automatically sends reminder emails on the second, fifth, and tenth day after the invitation was initially sent. @@ -130,7 +162,7 @@ NOTE: If a project does not have any maintainers, the notification is sent to the most recently active owners of the project's group. -![Manage access requests](img/access_requests_management_13_8.png) +![Manage access requests](img/access_requests_management_v13_9.png) If you change your mind before your request is approved, just click the **Withdraw Access Request** button. @@ -167,3 +199,27 @@ To remove a member from a project: A **Remove member** modal appears. 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. + +## Enable or disable improvements to project member management **(FREE SELF)** + +Project member management improvements are deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable the improvements. + +To disable them: + +```ruby +# For the instance +Feature.disable(:vue_project_members_list) +# For a single project +Feature.disable(:vue_project_members_list, Project.find(<project id>)) +``` + +To enable them: + +```ruby +# For the instance +Feature.enable(:vue_project_members_list) +# For a single project +Feature.enable(:vue_project_members_list, Project.find(<project id>)) +``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d17717fb29c..7000988d9bf 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -26,7 +26,7 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Members**. - ![share project with groups](img/share_project_with_groups_tab_v13_8.png) + ![share project with groups](img/share_project_with_groups_tab_v13_9.png) 1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. @@ -35,7 +35,7 @@ To share 'Project Acme' with the 'Engineering' group: 1. After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. - !['Engineering' group is listed in Groups tab](img/project_groups_tab_13_8.png) + !['Engineering' group is listed in Groups tab](img/project_groups_tab_v13_9.png) - The project is listed on the group dashboard. diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md deleted file mode 100644 index 5762177882e..00000000000 --- a/doc/user/project/merge_requests.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'merge_requests/index.md' ---- - -This document was moved to [merge_requests/index.md](merge_requests/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8adaae3b2ef..89fbc4cd89e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -23,7 +23,7 @@ of the merge request. ## Enabling commit edits from upstream members -From [GitLab 13.7 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), +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 will also be able to retry the pipelines and jobs of the merge request: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4e87876b036..36fb5cea4b0 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -13,12 +13,13 @@ with introducing a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request -After the merge request has been merged, a **Cherry-pick** button will be available +After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. ![Cherry-pick Merge Request](img/cherry_pick_changes_mr.png) -After you click that button, a modal will appear showing a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) +After you click that button, a modal displays a +[branch filter search box](../repository/branches/index.md#branch-filter-search-box) where you can choose to either: - Cherry-pick the changes directly into the selected branch. @@ -28,12 +29,12 @@ where you can choose to either: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. -When you cherry-pick a merge commit, GitLab will output a system note to the related merge -request thread crosslinking the new commit and the existing merge request. +When you cherry-pick a merge commit, GitLab displays a system note to the related merge +request thread. It crosslinks the new commit and the existing merge request. ![Cherry-pick tracking in Merge Request timeline](img/cherry_pick_mr_timeline_v12_9.png) -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. @@ -44,15 +45,15 @@ You can cherry-pick a commit from the commit details page: ![Cherry-pick commit](img/cherry_pick_changes_commit.png) -Similar to cherry-picking a merge request, you can opt to cherry-pick the changes +Similar to cherry-picking a merge request, you can cherry-pick the changes directly into the target branch or create a new merge request to cherry-pick the changes. -Please note that when cherry-picking merge commits, the mainline will always be the -first parent. If you want to use a different mainline then you need to do that +When cherry-picking merge commits, the mainline is always the +first parent. If you want to use a different mainline, you need to do that from the command line. -Here is a quick example to cherry-pick a merge commit using the second parent as the +Here's a quick example to cherry-pick a merge commit using the second parent as the mainline: ```shell diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index ca15ec154fc..0fb53884ea2 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Code Quality +# Code Quality **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your @@ -28,7 +28,7 @@ Code Quality: ## Code Quality Widget -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Going a step further, GitLab can show the Code Quality report right @@ -75,7 +75,7 @@ GitLab 11.4 or earlier, you can view the deprecated job definitions in the - Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). - Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running CodeQuality analysis more efficiently. -In either configuration, the runner mmust have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. +In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. Once you set up GitLab Runner, include the Code Quality template in your CI configuration: @@ -219,8 +219,8 @@ The end result is that: - Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. With this configuration, the run time for a second pipeline is much shorter. For example -this [small change](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) -to an [open merge request](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/pipelines) +this [small change](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) +to an [open merge request](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/pipelines) running Code Quality analysis ran significantly faster the second time: ![Code Quality sequential runs without DinD](img/code_quality_host_bound_sequential.png) @@ -358,7 +358,7 @@ After the Code Quality job completes: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. **(STARTER)** + Code Quality tab of the Pipeline Details page. **(PREMIUM)** ### Generating an HTML report @@ -411,7 +411,7 @@ plugins: enabled: true ``` -This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml) +This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) included in your project. Changes to the `plugins:` section do not affect the `exclude_patterns` section of the @@ -428,7 +428,7 @@ Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_proj A common issue is that the terms `Code Quality` (GitLab specific) and `Code Climate` (Engine used by GitLab) are very similar. You must add a **`.codeclimate.yml`** file to change the default configuration, **not** a `.codequality.yml` file. If you use -the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml) +the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. ### No Code Quality report is displayed in a Merge Request @@ -444,15 +444,15 @@ This can be due to multiple reasons: - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. -- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). +- Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) that are [ignored by GitLab](#implementing-a-custom-tool). You can: - Configure the Code Quality tool to not output those types. - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to - edit the `codeclimate.json` before the job completes. + edit the `gl-code-quality-report.json` before the job completes. ### Only a single Code Quality report is displayed, but more are defined GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. -To avoid confusion, configure only one job to generate a `codeclimate.json`. +To avoid confusion, configure only one job to generate a `gl-code-quality-report.json`. diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md deleted file mode 100644 index 2b7b2574ef7..00000000000 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'code_quality.md' ---- - -This document was moved to [another location](code_quality.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md deleted file mode 100644 index 5d61f2b36e8..00000000000 --- a/doc/user/project/merge_requests/container_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 5adc4ab6b6e..e5d3954cb41 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -178,7 +178,7 @@ fork from its upstream project in the **Settings > Advanced Settings** section b For further details, [see the forking workflow documentation](../repository/forking_workflow.md). -## New merge request by email **(CORE ONLY)** +## New merge request by email **(FREE SELF)** _This feature needs [incoming email](../../../administration/incoming_email.md) to be configured by a GitLab administrator to be available._ It isn't diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 0de9f246ceb..f4843b96c99 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,7 +4,7 @@ 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 --- -# Export Merge Requests to CSV **(CORE)** +# Export Merge Requests to CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md deleted file mode 100644 index 37c0d5b4e37..00000000000 --- a/doc/user/project/merge_requests/dast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/dast/index.md' ---- - -This document was moved to [another location](../../application_security/dast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md deleted file mode 100644 index dd5910121ed..00000000000 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/dependency_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/dependency_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index dc5e1f81a63..5be277c2f29 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -53,10 +53,10 @@ When you start a new merge request, you can immediately include the following options, or add them later by clicking the **Edit** button on the merge request's page at the top-right side: -- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees). +- [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- Require [approval](merge_request_approvals.md) from your team. **(STARTER)** +- Require [approval](merge_request_approvals.md) from your team. **(PREMIUM)** - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -87,9 +87,10 @@ Open the drop down box to search for the user you wish to assign, and the merge request will be added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). -#### Multiple assignees **(STARTER)** +#### Multiple assignees **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in GitLab 11.11. +> - Moved to GitLab Premium in 13.9 Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests @@ -119,7 +120,7 @@ It is also possible to manage multiple assignees: > - It's enabled on GitLab.com. > - It's recommended for production use. > - It can be enabled or disabled for a single project. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -136,7 +137,7 @@ This makes it easy to determine the relevant roles for the users involved in the To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. -#### Enable or disable Merge Request Reviewers **(CORE ONLY)** +#### Enable or disable Merge Request Reviewers **(FREE SELF)** Merge Request Reviewers is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -161,23 +162,23 @@ Feature.disable(:merge_request_reviewers) Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` -#### Approval Rule information for Reviewers **(STARTER)** +#### Approval Rule information for Reviewers **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. +> - Moved to GitLab Premium in 13.9. > - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51183) in GitLab 13.8. > - It's enabled on GitLab.com. > - It's recommended for production use. > - It can be enabled or disabled for a single project. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-approval-rule-information-for-reviewers). **(STARTER ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-approval-rule-information-for-reviewers). **(PREMIUM SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](merge_request_approvals.md#approval-rules) -below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as **Code Owner** without group detail. -We intend to iterate on this feature in future releases. +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: @@ -187,7 +188,7 @@ This example shows reviewers and approval rules in a merge request sidebar: ![Reviewer approval rules in sidebar](img/reviewer_approval_rules_sidebar_v13_8.png) -##### Enable or disable Approval Rule information for Reviewers **(STARTER ONLY)** +##### Enable or disable Approval Rule information for Reviewers **(PREMIUM SELF)** Merge Request Reviewers is under development and ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md deleted file mode 100644 index 4c598d851a9..00000000000 --- a/doc/user/project/merge_requests/license_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/license_compliance/index.md' ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md deleted file mode 100644 index 29afff289fd..00000000000 --- a/doc/user/project/merge_requests/maintainer_access.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'allow_collaboration.md' ---- - -This document was moved to [another location](allow_collaboration.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 887f563be51..36f5c5aed5f 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -5,27 +5,28 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge Request Approvals **(CORE)** +# Merge Request Approvals **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Core and higher tiers. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers. > - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. -Code review is an essential practice of every successful project, and giving your -approval once a merge request is in good shape is an important part of the review +Code review is an essential practice of every successful project. Approving a +merge request is an important part of the review process, as it clearly communicates the ability to merge the change. ## Optional Approvals > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Core and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and makes it easy for -maintainers to know when a change is ready to merge. Approvals in Core are optional and do +Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Free and higher tiers. +This provides a consistent mechanism for reviewers to approve merge requests, and ensures +maintainers know a change is ready to merge. Approvals in Free are optional, and do not prevent a merge request from being merged when there is no approval. -## Required Approvals **(STARTER)** +## Required Approvals **(PREMIUM)** -> [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. Available in [GitLab Starter](https://about.gitlab.com/pricing/) and higher tiers. +> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. +> - Moved to GitLab Premium in 13.9. Required approvals enable enforced code review by requiring specified people to approve a merge request before it can be merged. @@ -50,13 +51,12 @@ be merged, and optionally which users should do the approving. Approvals can be - [As project defaults](#adding--editing-a-default-approval-rule). - [Per merge request](#editing--overriding-approval-rules-per-merge-request). -If no approval rules are defined, any user can approve a merge request, though the default -minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings). +If no approval rules are defined, any user can approve a merge request. However, the default +minimum number of required approvers can still be set in the +[project settings for merge request approvals](#merge-request-approvals-project-settings). You can opt to define one single rule to approve a merge request among the available rules -or choose more than one. Single approval rules are available in GitLab Starter and higher tiers, -while [multiple approval rules](#multiple-approval-rules) are available in -[GitLab Premium](https://about.gitlab.com/pricing/) and above. +or choose more than one with [multiple approval rules](#multiple-approval-rules). NOTE: On GitLab.com, you can add a group as an approver if you're a member of that group or the @@ -64,7 +64,7 @@ group is public. #### Eligible Approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. The following users can approve merge requests: @@ -83,29 +83,31 @@ A group of users can also be added as approvers. In the future, group approvers [restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, as well as users who have committed +then that user is just counted once. The merge request author, and users who have committed to the merge request, do not count as eligible approvers, if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. -When an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, -indicating who has engaged in the merge request review. Authors and reviewers can also easily identify who they should reach out -to if they have any questions or inputs about the content of the merge request. +When an eligible approver comments on a merge request, it displays in the +**Commented by** column of the Approvals widget. It indicates who participated in +the merge request review. Authors and reviewers can also identify who they should reach out +to if they have any questions about the content of the merge request. ##### Implicit Approvers If the number of required approvals is greater than the number of assigned approvers, -approvals from other users will count towards meeting the requirement. These would be +approvals from other users counts towards meeting the requirement. These would be users with developer [permissions](../../permissions.md) or higher in the project who were not explicitly listed in the approval rules. ##### Code Owners as eligible approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files will become eligible approvers, together with members with Developer +corresponding files become eligible approvers, together with members with Developer or higher [permissions](../../permissions.md). To enable this merge request approval rule: @@ -117,7 +119,7 @@ To enable this merge request approval rule: ![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_7.png) Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab will accept approvals from +number of approvals you've set. GitLab accepts approvals from users with Developer or higher permissions, as well as by Code Owners, indistinguishably. @@ -126,7 +128,8 @@ Alternatively, you can **require** #### Merge Request approval segregation of duties -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to Premium in 13.9. Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) to a project sometimes need to be required approvers of a merge request, @@ -156,27 +159,27 @@ To add or edit the default merge request approval rule: 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers) + - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers will be suggested based on the previous authors of + in the search field, approvers are suggested based on the previous authors of the files being changed by the merge request. - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from the rule. 1. Click **Add approval rule** or **Update approval rule**. When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules will **not** be applied to existing merge +changes to these default rules are not applied to existing merge requests, except for changes to the [target branch](#scoped-to-protected-branch) of the rule. When approval rule overrides are not allowed, all changes to these default rules -will be applied to existing merge requests. Any approval rules that had previously been +are applied to existing merge requests. Any approval rules that had previously been manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, will not be modified. +period when approval rule overrides where allowed, are not modified. NOTE: If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules will be taken from the target (upstream) project, not the +the default approval rules are taken from the target (upstream) project, not the source (fork). ##### Editing / overriding approval rules per merge request @@ -195,8 +198,8 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- #### Set up an optional approval rule -MR approvals can be configured to be optional. -This can be useful if you're working on a team where approvals are appreciated, but not required. +MR approvals can be configured to be optional, which can help if you're working +on a team where approvals are appreciated, but not required. To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. @@ -211,16 +214,16 @@ as well as multiple default approval rules per project. Adding or editing multiple default rules is identical to [adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. Similarly, editing or overriding multiple approval rules per merge request is identical to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. -When an [eligible approver](#eligible-approvers) approves a merge request, it will -reduce the number of approvals left for all rules that the approver belongs to. +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left for all rules that the approver belongs to. ![Approvals premium merge request widget](img/approvals_premium_mr_widget_v13_3.png) @@ -269,7 +272,7 @@ The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. -Once the approval rules have been met, the merge request can be merged if there is nothing +After the approval rules have been met, the merge request can be merged if there is nothing else blocking it. Note that the merge request could still be blocked by other conditions, such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). @@ -291,7 +294,7 @@ To prevent that from happening: #### Resetting approvals on push You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals will persist +pushed to the source branch of the merge request. If disabled, approvals persist even if there are changes added to the merge request. To enable this feature: 1. Check the **Require new approvals when new commits are added to an MR.** @@ -300,11 +303,12 @@ even if there are changes added to the merge request. To enable this feature: NOTE: Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals will be reset if the target branch is changed. +from the UI. However, approvals are reset if the target branch is changed. -#### Allowing merge request authors to approve their own merge requests +#### Allowing merge request authors to approve their own merge requests **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. By default, projects are configured to prevent merge requests from being approved by their own authors. To change this setting: @@ -315,9 +319,10 @@ their own authors. To change this setting: Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). -#### Prevent approval of merge requests by their committers +#### Prevent approval of merge requests by their committers **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. You can prevent users that have committed to a merge request from approving it. To enable this feature: @@ -327,12 +332,13 @@ enable this feature: #### Require authentication when approving a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. NOTE: To require authentication when approving a merge request, you must enable **Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin area. +in the Admin Area. You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 4a596ed6139..646d77391a3 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -17,7 +17,7 @@ then it cannot be merged until its dependency is itself merged. NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **CORE** or +only enforced for the dependent merge request. A merge request in a **FREE** or **STARTER** project can be a dependency of a **PREMIUM** merge request, but not vice-versa. diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md deleted file mode 100644 index f8d15f31875..00000000000 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../discussions/index.md' ---- - -This document was moved to [another location](../../discussions/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md deleted file mode 100644 index 48d32d2882f..00000000000 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -redirect_to: 'merge_when_pipeline_succeeds.md' ---- - -This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). - ->[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7135) by the "Rename MWBS service to Merge When Pipeline Succeeds" change. - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 b813e4f7d28..5efb8d9ff40 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -42,8 +42,12 @@ complete, the merge is blocked until you resolve all existing threads. ## Only allow merge requests to be merged if the pipeline succeeds -You can prevent merge requests from being merged if their pipeline did not succeed -or if there are threads to be resolved. This works for both: +You can prevent merge requests from being merged if: + +- No pipeline ran. +- The pipeline did not succeed. + +This works for both: - GitLab CI/CD pipelines - Pipelines run from an [external CI integration](../integrations/overview.md#integrations-listing) @@ -58,6 +62,7 @@ CI providers with this feature. To enable it, you must: 1. Press **Save** for the changes to take effect. This setting also prevents merge requests from being merged if there is no pipeline. +You should be careful to configure CI/CD so that pipelines run for every merge request. ### Limitations diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 99e70f35d6d..b2aedb7d95f 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -10,13 +10,13 @@ type: reference, concepts Merge conflicts occur when two branches have different changes that cannot be merged automatically. -Git is able to automatically merge changes between branches in most cases, but -there are situations where Git will require your assistance to resolve the +Git can merge changes between branches in most cases, but +occasionally Git requires your assistance to resolve the conflicts manually. Typically, this is necessary when people change the same parts of the same files. -GitLab will prevent merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases within GitLab +GitLab prevents merge requests from being merged until all conflicts are +resolved. Conflicts can be resolved locally, or in many cases in GitLab (see [conflicts available for resolution](#conflicts-available-for-resolution) for information on when this is available). @@ -24,35 +24,30 @@ for information on when this is available). NOTE: GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. This allows the merge -commit to be reviewed and tested before the changes are merged, preventing +is not automatically merged into the target branch. The merge +commit can be reviewed and tested before the changes are merged. This prevents unintended changes entering the target branch without review or breaking the build. ## Resolve conflicts: interactive mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5479) in GitLab 8.11. - -Clicking this will show a list of files with conflicts, with conflict sections +Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections highlighted: ![Conflict section](img/conflict_section.png) -Once all conflicts have been marked as using 'ours' or 'theirs', the conflict -can be resolved. This will perform a merge of the target branch of the merge -request into the source branch, resolving the conflicts using the options +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. ## Resolve conflicts: inline editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6374) in GitLab 8.13. - -The merge conflict resolution editor allows for more complex merge conflicts, -which require the user to manually modify a file in order to resolve a conflict, -to be solved right form the GitLab interface. Use the **Edit inline** button -to open the editor. Once you're sure about your changes, hit the -**Commit to source branch** button. +Some merge conflicts are more complex, requiring you to manually modify a file to +resolve them. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface. Click **Edit inline** to open the editor. +After you're sure about your changes, click **Commit to source branch**. ![Merge conflict editor](img/merge_conflict_editor.png) @@ -66,13 +61,16 @@ GitLab allows resolving conflicts in a file where all of the below are true: - The file, with conflict markers added, is not over 200 KB in size - The file exists under the same path in both branches -If any file with conflicts in that merge request does not meet all of these -criteria, the conflicts for that merge request cannot be resolved in the UI. +If any file in your merge request containing conflicts can't meet all of these +criteria, you can't resolve the merge conflict in the UI. Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this will not create a conflict: on branch `a`, doing `git mv file1 -file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be -present in the branch after the merge request is merged. +example, this does not create a conflict: + +1. On branch `a`, doing `git mv file1 file2` +1. On branch `b`, doing `git mv file1 file3`. + +Instead, both files are present in the branch after the merge request is merged. <!-- ## Troubleshooting 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 e2d6ba9ea1c..4efeb3b7938 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 @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Reviewing and managing merge requests **(CORE)** +# Reviewing and managing merge requests **(FREE)** Merge requests are the primary method of making changes to files in a GitLab project. Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), @@ -13,10 +13,10 @@ which is then reviewed, and accepted (or rejected). ## View project merge requests -View all the merge requests within a project by navigating to **Project > Merge Requests**. +View all the merge requests in a project by navigating to **Project > Merge Requests**. -When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). +When you access your project's merge requests, GitLab displays them in a list. +Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). ![Project merge requests list view](img/project_merge_requests_list_view_v13_5.png) @@ -32,7 +32,7 @@ You can [search and filter the results](../../search/index.md#filtering-issue-an A merge commit is created for every merge, but the branch is only merged if a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build will also succeed after merging. +succeeded, the target branch build also succeeds after the merge. Navigate to a project's settings, select the **Merge commit with semi-linear history** option under **Merge Requests: Merge method** and save your changes. @@ -80,16 +80,19 @@ Click **Expand file** on any file to view the changes for that file. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. -For larger merge requests it might sometimes be useful to review single files at a time. To enable, -from your avatar on the top-right navigation bar, click **Settings**, and go to **Preferences** on the left -sidebar. Scroll down to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -Click **Save changes** to apply. +For larger merge requests, consider reviewing one file at a time. To enable this feature: -From there, when reviewing merge requests' **Changes** tab, you will see only one file at a time. You can then click the buttons **Prev** and **Next** to view the other files changed. +1. In the top right corner of the navigation bar, click your user avatar. +1. Click **Settings**. +1. In the left sidebar, go to **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Click **Save changes** to apply. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files. ![File-by-file diff navigation](img/file_by_file_v13_2.png) -From [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) onwards, if you want to change +In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change this behavior, you can do so from your **User preferences** (as explained above) or directly in a merge request: @@ -104,10 +107,14 @@ browser's cookies or change this behavior again. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. -To seamlessly navigate among commits in a merge request, from the **Commits** tab, click one of -the commits to open the single-commit view. From there, you can navigate among the commits -by clicking the **Prev** and **Next** buttons on the top-right of the page or by using the -<kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. +To seamlessly navigate among commits in a merge request: + +1. Click the **Commits** tab. +1. Click a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Clicking **Prev** and **Next** buttons on the top-right of the page. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. ![Merge requests commit navigation](img/commit_nav_v13_4.png) @@ -120,7 +127,7 @@ to expand the entire file. ![Incrementally expand merge request diffs](img/incrementally_expand_merge_request_diffs_v12_2.png) -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205401) in GitLab 13.1, when viewing a +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the entire content by clicking **Show file contents**. @@ -136,12 +143,53 @@ 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. +> - It's deployed behind a feature flag, 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-file-views). **(FREE SELF)** + +When reviewing a merge request with many files multiple times, it may be useful to the reviewer +to focus on new changes and ignore the files that they have already reviewed and don't want to +see anymore unless they are changed again. + +To mark a file as viewed: + +1. Go to the merge request's **Diffs** tab. +1. On the right-top of the file, locate the **Viewed** checkbox. +1. Check it to mark the file as viewed. + +Once checked, the file remains marked for that reviewer unless there are newly introduced +changes to its content or the checkbox is unchecked. + +### Enable or disable file views **(FREE SELF)** + +The file view feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:local_file_reviews) +``` + +To disable it: + +```ruby +Feature.disable(:local_file_reviews) +``` + ## Perform inline code reviews > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. -GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **{comment}** **comment** icon in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. +In a merge request, you can leave comments in any part of the file being changed. +In the Merge Request Diff UI, click the **{comment}** **comment** icon in the gutter +to expand the diff lines and leave a comment, just as you would for a changed line. ![Comment on any diff file line](img/comment-on-any-diff-line.png) @@ -153,7 +201,7 @@ in a Merge Request. To do so, click the **{comment}** **comment** icon in the gu > - It's enabled on GitLab.com. > - It can be disabled or enabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments). **(FREE SELF)** GitLab provides a way to select which lines of code a comment refers to. After starting a comment a dropdown selector is shown to select the first line that this comment refers to. @@ -169,7 +217,7 @@ above it. ![Multiline comment selection displayed above comment](img/multiline-comment-saved.png) -### Enable or disable multiline comments **(CORE ONLY)** +### Enable or disable multiline comments **(FREE SELF)** The multiline comments feature is under development but ready for production use. It is deployed behind a feature flag that is **disabled by default**. @@ -191,31 +239,30 @@ Feature.enable(:multiline_comments) ## Pipeline status in merge requests widgets If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you will be able to see: +you can see: - Both pre-merge and post-merge pipelines and the environment information if any. - Which deployments are in progress. -If there's an [environment](../../../ci/environments/index.md) and the application is -successfully deployed to it, the deployed environment and the link to the -Review App will be shown as well. +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 default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button -When the pipeline fails in a merge request but it can be merged nonetheless, -the **Merge** button will be colored in red. +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 master branch and then triggers a deployment to the staging +is merged into the `master` branch and then triggers a deployment to the staging environment. -Deployments that are ongoing will be shown, as well as the deploying/deployed state +Ongoing deployments are shown, and the state (deploying or deployed) for environments. If it's the first time the branch is deployed, the link -will return a `404` error until done. During the deployment, the stop button will -be disabled. If the pipeline fails to deploy, the deployment information will be hidden. +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. ![Merge request pipeline](img/merge_request_pipeline.png) @@ -223,14 +270,15 @@ 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). +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 -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. +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 @@ -240,21 +288,26 @@ faster to preview proposed modifications. ## Associated features -There is also a large number of features to associated to merge requests: - -| Feature | Description | -|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | -| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | -| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | -| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | -| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | -| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | -| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | +These features are associated with merge requests: + +- [Bulk editing merge requests](../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](cherry_pick_changes.md): + Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](revert_changes.md): + Revert changes from any commit from a merge request. ## Troubleshooting -Sometimes things don't go as expected in a merge request, here are some +Sometimes things don't go as expected in a merge request. Here are some troubleshooting steps. ### Merge request cannot retrieve the pipeline status @@ -264,7 +317,7 @@ This can occur if Sidekiq doesn't pick up the changes fast enough. #### Sidekiq Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status will update automatically. +seconds and the status should update automatically. #### Bug @@ -280,12 +333,9 @@ Merge Request again. ## Tips -Here are some tips that will help you be more efficient with merge requests in +Here are some tips to help you be more efficient with merge requests in the command line. -NOTE: -This section might move in its own document in the future. - ### Copy the branch name for local checkout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. @@ -294,7 +344,7 @@ The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request. To copy the branch reference into your clipboard, click the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. You can then use it to checkout the branch locally +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally via command line by running `git checkout <branch-name>`. ### Checkout merge requests locally through the `head` ref @@ -303,7 +353,7 @@ A merge request contains all the history from a repository, plus the additional commits added to the branch associated with the merge request. Here's a few ways to checkout a merge request locally. -Please note that you can checkout a merge request locally even if the source +You can checkout a merge request locally even if the source project is a fork (even a private fork) of the target project. This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) @@ -312,10 +362,10 @@ request via its ID instead of its branch. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab 13.4, 14 days after a merge request gets closed or merged, the merge request -`head` ref will be deleted. This means that the merge request will not be available +`head` ref is deleted. This means that the merge request is not available for local checkout via the merge request `head` ref anymore. The merge request -can still be re-opened. Also, as long as the merge request's branch -exists, you can still check out the branch as it won't be affected. +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. #### Checkout locally by adding a Git alias @@ -334,7 +384,7 @@ from the `origin` remote, do: git mr origin 5 ``` -This will fetch the merge request into a local `mr-origin-5` branch and check +This fetches the merge request into a local `mr-origin-5` branch and check it out. #### Checkout locally by modifying `.git/config` for a given repository diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md deleted file mode 100644 index 11f85749fb7..00000000000 --- a/doc/user/project/merge_requests/sast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/sast/index.md' ---- - -This document was moved to [another location](../../application_security/sast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md deleted file mode 100644 index 5d61f2b36e8..00000000000 --- a/doc/user/project/merge_requests/sast_docker.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 93b85ce8669..5311d833aec 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -8,7 +8,7 @@ type: reference, concepts # Squash and merge > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Core in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)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. @@ -110,7 +110,6 @@ squashing can itself be considered equivalent to rebasing. > - It's enabled on GitLab.com. > - It can be enabled per project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options). **(CORE ONLY)** With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. @@ -133,31 +132,6 @@ NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. -### Enable or disable Squash Commit Options **(CORE ONLY)** - -Squash Commit Options is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:squash_options) -# or by project -Feature.enable(:squash_options, Project.find(<project ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:squash_options) -# or by project -Feature.disable(:squash_options, Project.find(<project ID>)) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues 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 7417320eea0..43ab03114fa 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 @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Draft merge requests **(CORE)** +# Draft merge requests **(FREE)** If a merge request is not yet ready to be merged, perhaps due to continued development or open threads, you can prevent it from being accepted before it's ready by flagging -it as a **Draft**. This will disable the "Merge" button, preventing it from -being merged, and it will stay disabled until the "Draft" flag has been removed. +it as a **Draft**. This disables the **Merge** button, preventing it from +being merged. It stays disabled until the **Draft** flag has been removed. ![Blocked Merge Button](img/draft_blocked_merge_button_v13_2.png) @@ -22,7 +22,7 @@ To run pipelines for merged results, you must [remove the draft status](#removin ## Adding the "Draft" flag to a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a Draft: @@ -30,15 +30,15 @@ There are several ways to flag a merge request as a Draft: - Click the **Mark as draft** button on the top-right corner of the merge request's page. - Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on **Start the title with Draft:**, under the title box, when editing the merge request's - description will have the same effect. + description has the same effect. - **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. - **WIP** still works but was deprecated in favor of **Draft**. It will be removed in the next major version (GitLab 14.0). + **WIP** still works but was deprecated in favor of **Draft**. It is scheduled for removal in the next major version (GitLab 14.0). - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and doing it again in another - commit will have no effect. + commit has no effect. ## Removing the "Draft" flag from a merge request @@ -48,10 +48,10 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the - Click the **Mark as ready** button on the top-right corner of the merge request's page. - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge - request's description, will have the same effect. + request's description, has the same effect. - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Click on the **Resolve Draft status** button near the bottom of the merge request description, next to the **Merge** button (see [image above](#draft-merge-requests)). Must have at least Developer level permissions on the project for the button to @@ -60,8 +60,8 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the ## Including/excluding WIP merge requests when searching When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests by adding a "WIP" filter in the search box, and choosing "Yes" -(to include) or "No" (to exclude). +WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** +to include, or **No** to exclude. ![Filter WIP MRs](img/filter_wip_merge_requests.png) diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index acf32bb0f92..d7ca2eae831 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Milestones **(CORE)** +# Milestones **(FREE)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md deleted file mode 100644 index e60e7d93d12..00000000000 --- a/doc/user/project/operations/alert_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/index.md' ---- - -This document was moved to [another location](../../../operations/incident_management/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md deleted file mode 100644 index ef106181acc..00000000000 --- a/doc/user/project/operations/dashboard_settings.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/settings.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md deleted file mode 100644 index 399ab0d53dc..00000000000 --- a/doc/user/project/operations/error_tracking.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/error_tracking.md' ---- - -This document was moved to [another location](../../../operations/error_tracking.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md deleted file mode 100644 index 03f2cad6d78..00000000000 --- a/doc/user/project/operations/feature_flags.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/feature_flags.md' ---- - -This document was moved to [another location](../../../operations/feature_flags.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md deleted file mode 100644 index d19cf393883..00000000000 --- a/doc/user/project/operations/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/index.md' ---- - -This document was moved to [another location](../../../operations/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md deleted file mode 100644 index ef106181acc..00000000000 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/settings.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md deleted file mode 100644 index dcf9894f9e1..00000000000 --- a/doc/user/project/operations/tracing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/tracing.md' ---- - -This document was moved to [another location](../../../operations/tracing.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven_repository.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md deleted file mode 100644 index f874b05e7e2..00000000000 --- a/doc/user/project/packages/npm_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/npm_registry/index.md' ---- - -This document was moved to [another location](../../packages/npm_registry/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 aa06a15a8c0..86e34842aaf 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 @@ -19,7 +19,7 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. WARNING: -This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(FREE SELF)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements @@ -28,7 +28,8 @@ Before you can enable automatic provisioning of an SSL certificate for your doma - Created a [project](../index.md#getting-started) in GitLab containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](index.md) - pointing it to your Pages website. + pointing it to your Pages website. The top-level domain (`.com`) must be a + [public suffix](https://publicsuffix.org/). - [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) and verified your ownership. - Verified your website is up and running, accessible through your custom 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 e8c6305dbab..d9f57253396 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 @@ -32,7 +32,9 @@ nor credit card transactions, then why do we need secure connections? Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. +<!-- vale gitlab.Spelling = NO --> Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): +<!-- vale gitlab.rulename = YES --> > _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md deleted file mode 100644 index 2cf118c9066..00000000000 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_forked_sample_project.md' ---- - -This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md deleted file mode 100644 index 2fc833fbd34..00000000000 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_ci_cd_template.md' ---- - -This document was moved to [another location](pages_ci_cd_template.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md deleted file mode 100644 index 0dab1f6ee19..00000000000 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_new_project_template.md' ---- - -This document was moved to [pages_new_project_template.md](pages_new_project_template.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 c7916b7c01e..60f8533afc8 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 @@ -52,5 +52,5 @@ You can take some **optional** further steps: ![Change repository's path](../img/change_path_v12_10.png) - - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) + - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md deleted file mode 100644 index 361323a9073..00000000000 --- a/doc/user/project/pages/getting_started_part_four.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'getting_started/pages_from_scratch.md' ---- - -This document was moved to [getting_started/pages_from_scratch.md](getting_started/pages_from_scratch.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 801fe0c7ef0..dee021b8225 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 baseurls +# GitLab Pages domain names, URLs, and base URLs On this document, learn how to name your project for GitLab Pages according to your intended website's URL. @@ -78,7 +78,7 @@ To understand Pages domains clearly, read the examples below. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -## URLs and baseurls +## URLs and base URLs NOTE: The `baseurl` option might be called named differently in some static site generators. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md deleted file mode 100644 index 9d7f401ca91..00000000000 --- a/doc/user/project/pages/getting_started_part_three.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'custom_domains_ssl_tls_certification/index.md' ---- - -This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md deleted file mode 100644 index 4b2b186ca28..00000000000 --- a/doc/user/project/pages/getting_started_part_two.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md#getting-started). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index c9e28bf15c2..6eb06972945 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -103,7 +103,7 @@ optionally secure it with SSL/TLS certificates. If you're using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). -If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), +If you're using a self-managed instance (Free, Premium, or Ultimate), your websites are published on your own server, according to the [Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 8380f367212..fbc86abbe66 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -63,7 +63,7 @@ If the case of `404.html`, there are different scenarios. For example: You can configure redirects for your site using a `_redirects` file. To learn more, read the [redirects documentation](redirects.md). -## GitLab Pages Access Control **(CORE)** +## GitLab Pages Access Control **(FREE)** To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index a2a17a4f2ca..2e0fc87b3df 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -38,7 +38,9 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v - **Only project members**: Only project members are able to browse the website. - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. -1. Click **Save changes**. +1. Click **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses + a caching mechanism for efficiency. Your changes may not take effect until that cache is + invalidated, which usually takes less than a minute. The next time someone tries to access your website and the access control is enabled, they're presented with a page to sign into GitLab and verify they diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md deleted file mode 100644 index cf5f33534cd..00000000000 --- a/doc/user/project/pipelines/job_artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/job_artifacts.md' ---- - -This document was moved to [another location](../../../ci/pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md deleted file mode 100644 index 52352a29c5a..00000000000 --- a/doc/user/project/pipelines/schedules.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/schedules.md' ---- - -This document was moved to [another location](../../../ci/pipelines/schedules.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md deleted file mode 100644 index f19f28743a8..00000000000 --- a/doc/user/project/pipelines/settings.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/settings.md' ---- - -This document was moved to [another location](../../../ci/pipelines/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 5754a3b7a9d..37324b02437 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -13,7 +13,7 @@ further restrictions on certain branches, they can be protected. ## Overview -By default, a protected branch does four simple things: +By default, a protected branch does these things: - It prevents its creation, if not already created, from everybody except users with Maintainer permission. @@ -21,58 +21,60 @@ By default, a protected branch does four simple things: - It prevents **anyone** from force pushing to the branch. - It prevents **anyone** from deleting the branch. -NOTE: -A GitLab administrator is allowed to push to the protected branches. +**Permissions:** -See the [Changelog](#changelog) section for changes over time. +- GitLab administrators are allowed to push to the protected branches. +- Users with [Developer permissions](../permissions.md) are allowed to + create a project in a group, but might not be allowed to initially + push to the [default branch](repository/branches/index.md#default-branch). The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +See the [Changelog](#changelog) section for changes over time. + ## Configuring protected branches -To protect a branch, you need to have at least Maintainer permission level. Note -that the `master` branch is protected by default. +To protect a branch, you need to have at least Maintainer permission level. +The `master` branch is protected by default. -1. Navigate to your project's **Settings ➔ Repository** +1. In your project, go to **Settings > Repository**. 1. Scroll to find the **Protected branches** section. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch. ![Protected branches page](img/protected_branches_page_v12_3.png) -1. Once done, the protected branch will appear in the "Protected branches" list. +1. Once done, the protected branch displays in the **Protected branches** list. ![Protected branches list](img/protected_branches_list_v12_3.png) ## Using the Allowed to merge and Allowed to push settings -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11. - In GitLab 8.11 and later, we added another layer of branch protection which provides -more granular management of protected branches. The "Developers can push" -option was replaced by an "Allowed to push" setting which can be set to -allow/prohibit Maintainers and/or Developers to push to a protected branch. +more granular management of protected branches. The **Developers can push** +option was replaced by **Allowed to push**. You can set this value to allow +or prohibit Maintainers and/or Developers to push to a protected branch. -Using the "Allowed to push" and "Allowed to merge" settings, you can control +Using the **Allowed to push** and **Allowed to merge** settings, you can control the actions that different roles can perform with the protected branch. -For example, you could set "Allowed to push" to "No one", and "Allowed to merge" -to "Developers + Maintainers", to require _everyone_ to submit a merge request for +For example, you could set **Allowed to push** to "No one", and **Allowed to merge** +to "Developers + Maintainers", to require everyone to submit a merge request for changes going into the protected branch. This is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). However, there are workflows where that is not needed, and only protecting from force pushes and branch removal is useful. For those workflows, you can allow everyone with write access to push to a protected branch by setting -"Allowed to push" to "Developers + Maintainers". +**Allowed to push** to "Developers + Maintainers". -You can set the "Allowed to push" and "Allowed to merge" options while creating +You can set the **Allowed to push** and **Allowed to merge** options while creating a protected branch or afterwards by selecting the option you want from the -dropdown list in the "Already protected" area. +dropdown list in the **Already protected** area. ![Developers can push](img/protected_branches_devs_can_push_v12_3.png) If you don't choose any of those options while creating a protected branch, -they are set to "Maintainers" by default. +they are set to Maintainers by default. ### Allow Deploy Keys to push to a protected branch @@ -88,7 +90,7 @@ Deploy keys can be selected in the **Allowed to push** dropdown when: - Defining a protected branch. - Updating an existing branch. -Select a deploy key to allow the owner of the key to push to the chosen protected branch, +Select a deploy key to allow the key's owner to push to the chosen protected branch, even if they aren't a member of the related project. The owner of the selected deploy key must have at least read access to the given project. @@ -101,26 +103,22 @@ Deploy Keys are not available in the **Allowed to merge** dropdown. ![Deploy Keys on protected branches](img/protected_branches_deploy_keys_v13_5.png) -## Restricting push and merge access to certain users **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11. +## Restricting push and merge access to certain users **(PREMIUM)** -With GitLab Enterprise Edition you can restrict access to protected branches -by choosing a role (Maintainers, Developers) as well as certain users. From the +With GitLab Premium you can restrict access to protected branches +by choosing a role (Maintainers, Developers) and certain users. From the dropdown menu select the role and/or the users you want to have merge or push access. ![Select roles and users](img/protected_branches_select_roles_and_users.png) -Click **Protect** and the branch will appear in the "Protected branch" list. +Click **Protect** and the branch displays in the **Protected branch** list. ![Roles and users list](img/protected_branches_select_roles_and_users_list.png) ## Wildcard protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665) in GitLab 8.10. - -You can specify a wildcard protected branch, which will protect all branches +You can specify a wildcard protected branch, which protects all branches matching the wildcard. For example: | Wildcard Protected Branch | Matching Branches | @@ -129,15 +127,15 @@ matching the wildcard. For example: | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -Protected branch settings (like "Developers can push") apply to all matching +Protected branch settings, like **Developers can push**, apply to all matching branches. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch. In that case, if _any_ of these protected branches have a setting like -"Allowed to push", then `production-stable` will also inherit this setting. +"Allowed to push", then `production-stable` also inherit this setting. -If you click on a protected branch's name, you will be presented with a list of +If you click on a protected branch's name, GitLab displays a list of all matching branches: ![Protected branch matches](img/protected_branches_matches.png) @@ -151,41 +149,36 @@ When a protected branch or wildcard protected branches are set to Developers (and users with higher [permission levels](../permissions.md)) are allowed to create a new protected branch as long as they are [**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). -This can only be done via the UI or through the API (to avoid creating protected -branches accidentally from the command line or from a Git client application). +This can only be done by using the UI or through the API, to avoid creating protected +branches accidentally from the command line or from a Git client application. To create a new branch through the user interface: -1. Visit **Repository > Branches**. +1. Go to **Repository > Branches**. 1. Click on **New branch**. -1. Fill in the branch name and select an existing branch, tag, or commit that - the new branch will be based off. Only existing protected branches and commits - that are already in protected branches will be accepted. +1. Fill in the branch name and select an existing branch, tag, or commit to + base the new branch on. Only existing protected branches and commits + that are already in protected branches are accepted. ## Deleting a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3. - -From time to time, it may be required to delete or clean up branches that are -protected. +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 +branches by using the GitLab web interface: -User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via the GitLab web interface: - -1. Visit **Repository > Branches** -1. Click on the delete icon next to the branch you wish to delete -1. In order to prevent accidental deletion, an additional confirmation is - required +1. Go to **Repository > Branches**. +1. Click on the delete icon next to the branch you wish to delete. +1. To prevent accidental deletion, an additional confirmation is required. ![Delete protected branches](img/protected_branches_delete.png) -Deleting a protected branch is only allowed via the web interface, not via Git. +Deleting a protected branch is allowed only by using the web interface; not from Git. This means that you can't accidentally delete a protected branch from your command line or a Git client application. ## Protected Branches approval by Code Owners **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. It is possible to require at least one approval by a [Code Owner](code_owners.md) to a file changed by the @@ -208,7 +201,7 @@ To enable Code Owner's approval to branches already protected: ![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v12_4.png) -When enabled, all merge requests targeting these branches will require approval +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. @@ -224,26 +217,9 @@ for details about the pipelines security model. ## Changelog -**13.5** - -- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). - -**11.9** - -- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. - -**9.2** - -- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)). - -**8.11** - -- Allow creating protected branches that can't be pushed to ([merge request !5081](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081)). - -**8.10** - -- Allow developers without push access to merge into a protected branch ([merge request !4892](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4892)). -- Allow specifying protected branches using wildcards ([merge request !4665](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665)). +- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). +- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) + by Developers (and users with higher permission levels) through the API and the user interface. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 7e09c526312..a6f2d645198 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -15,11 +15,13 @@ This feature evolved out of [protected branches](protected_branches.md) ## Overview -Protected tags will prevent anyone from updating or deleting the tag, and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags. +Protected tags prevent anyone from updating or deleting the tag, and prevent +creation of matching tags based on the permissions you have selected. By default, +anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags. ## Configuring protected tags -To protect a tag, you need to have at least Maintainer permission level. +To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). 1. Navigate to the project's **Settings > Repository**: @@ -29,17 +31,18 @@ To protect a tag, you need to have at least Maintainer permission level. ![Protected tags page](img/protected_tags_page_v12_3.png) -1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**: +1. From the **Allowed to create** dropdown, select users with permission to create + matching tags, and click **Protect**: ![Allowed to create tags dropdown](img/protected_tags_permissions_dropdown_v12_3.png) -1. Once done, the protected tag will appear in the **Protected tags** list: +1. After done, the protected tag displays in the **Protected tags** list: ![Protected tags list](img/protected_tags_list_v12_3.png) ## Wildcard protected tags -You can specify a wildcard protected tag, which will protect all tags +You can specify a wildcard protected tag, which protects all tags matching the wildcard. For example: | Wildcard Protected Tag | Matching Tags | @@ -52,9 +55,9 @@ matching the wildcard. For example: Two different wildcards can potentially match the same tag. For example, `*-stable` and `production-*` would both match a `production-stable` tag. In that case, if _any_ of these protected tags have a setting like -**Allowed to create**, then `production-stable` will also inherit this setting. +**Allowed to create**, then `production-stable` also inherit this setting. -If you click on a protected tag's name, you will be presented with a list of +If you click on a protected tag's name, GitLab displays a list of all matching tags: ![Protected tag matches](img/protected_tag_matches.png) diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 64be3182dab..ac65fabd6a7 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -34,9 +34,9 @@ The following quick actions are applicable to descriptions, discussions and thre | `/assign @user` | ✓ | ✓ | | Assign one user. | | `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | | `/assign me` | ✓ | ✓ | | Assign yourself. | -| `/assign_reviewer @user` | | ✓ | | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | -| `/assign_reviewer me` | | ✓ | | Assign yourself as a reviewer. | +| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | | ✓ | | Assign one user as a reviewer. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | | ✓ | | Assign yourself as a reviewer. | | `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | | `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | | `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | @@ -49,7 +49,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/done` | ✓ | ✓ | ✓ | Mark to do as done. | | `/draft` | | ✓ | | Toggle the draft status. | | `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | +| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | | `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | | `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | @@ -62,7 +62,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | | `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | | `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | -| `/rebase` | | ✓ | | Rebase source branch. This will schedule a background task that attempt to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` will be ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab will display a message that a rebase cannot be scheduled. Rebase failures will be displayed with the merge request status. | +| `/rebase` | | ✓ | | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | @@ -87,8 +87,8 @@ The following quick actions are applicable to descriptions, discussions and thre | `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | | `/unassign` | | ✓ | | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | -| `/unassign_reviewer` | | ✓ | | Remove all reviewers. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | +| `/unassign_reviewer` or `/remove_reviewer` | | ✓ | | Remove all reviewers. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | | `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | | `/unlock` | ✓ | ✓ | | Unlock the discussions. | diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md deleted file mode 100644 index 6dd5a6f0b0d..00000000000 --- a/doc/user/project/releases.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'releases/index.md' ---- - -This document was moved to [another location](releases/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 90d7ac0a3c2..d03cc0495c1 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -407,7 +407,7 @@ Here is an example of a release evidence object: } ``` -### Collect release evidence **(PREMIUM ONLY)** +### Collect release evidence **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index ffd4b383bcb..abe533172b9 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -53,14 +53,14 @@ the target is the project's **default branch**. The default branch is also initially [protected](../../protected_branches.md#protected-branches) against accidental deletion and forced pushes. -### Custom initial branch name **(CORE ONLY)** +### Custom initial branch name **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. > - It's deployed behind a feature flag, enabled by default. > - It's enabled on GitLab.com. > - It cannot be enabled or disabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(FREE SELF)** By default, when you create a new project in GitLab, the initial branch is called `master`. For self-managed instances, a GitLab administrator can customize the initial branch name to something @@ -71,7 +71,7 @@ else. This way, every new project created from then on will start from the custo 1. Change the default initial branch to a custom name of your choice. 1. **Save Changes**. -#### Enable or disable custom initial branch name **(CORE ONLY)** +#### Enable or disable custom initial branch name **(FREE SELF)** Setting the default initial branch name is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 4f996df5fef..df3e24fbf30 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -17,8 +17,8 @@ project. ![Find file button](img/file_finder_find_button_v12_10.png) -For those who prefer to keep their fingers on the keyboard, there is a -[shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ +If you prefer to keep their fingers on the keyboard, use the +[shortcut button](../../shortcuts.md), which you can invoke from anywhere in a project. Press `t` to launch the File search function when in **Issues**, diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index fb798738160..7847930366a 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -23,107 +23,28 @@ Rewriting repository history is a destructive operation. Make sure to back up yo you begin. The best way back up a repository is to [export the project](../settings/import_export.md#exporting-a-project-and-its-data). -NOTE: -Git LFS files can only be removed by an Administrator using a -[Rake task](../../../raketasks/cleanup.md). Removal of this limitation -[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/223621). - ## Purge files from repository history -To reduce the size of your repository in GitLab, you must remove references to large files from branches, tags, and +To reduce the size of your repository in GitLab, you must first remove references to large files from branches, tags, *and* other internal references (refs) that are automatically created by GitLab. These refs include: - `refs/merge-requests/*` for merge requests. - `refs/pipelines/*` for [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). - `refs/environments/*` for environments. +- `refs/keep-around/*` are created as hidden refs to prevent commits referenced in the database from being removed -Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to -download all the advertised refs. - -1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) - using a supported package manager or from source. - -1. Clone a fresh copy of the repository using `--bare` and `--mirror`: - - ```shell - git clone --bare --mirror https://gitlab.example.com/my/project.git - ``` - -1. Using `git filter-repo`, purge any files from the history of your repository. - - To purge large files, the `--strip-blobs-bigger-than` option can be used: - - ```shell - git filter-repo --strip-blobs-bigger-than 10M - ``` - - To purge large files stored using Git LFS, the `--blob--callback` option can - be used. The example below, uses the callback to read the file size from the - Git LFS pointer, and removes files larger than 10MB. - - ```shell - git filter-repo --blob-callback ' - if blob.data.startswith(b"version https://git-lfs.github.com/spec/v1"): - size_in_bytes = int.from_bytes(blob.data[124:], byteorder="big") - if size_in_bytes > 10*1000: - blob.skip() - ' - ``` - - To purge specific large files by path, the `--path` and `--invert-paths` options can be combined: - - ```shell - git filter-repo --path path/to/big/file.m4v --invert-paths - ``` - - See the - [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) - for more examples and the complete documentation. - -1. Force push your changes to overwrite all branches on GitLab: - - ```shell - git push origin --force 'refs/heads/*' - ``` - - [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must - remove branch protection, push, and then re-enable protected branches. - -1. To remove large files from tagged releases, force push your changes to all tags on GitLab: - - ```shell - git push origin --force 'refs/tags/*' - ``` - - [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag - protection, push, and then re-enable protected tags. - -1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. - - ```shell - git push origin --force 'refs/replace/*' - ``` - - Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. - -1. Run a [repository cleanup](#repository-cleanup). - -NOTE: -Project statistics are cached for performance. You may need to wait 5-10 minutes -to see a reduction in storage utilization. - -## Purge files from GitLab storage - -In addition to the refs mentioned above, GitLab also creates hidden `refs/keep-around/*`to prevent commits being deleted. Hidden refs are not advertised, which means we can't download them using Git, but these refs are included in a project export. +These refs are not automatically downloaded and hidden refs are not advertised, but we can remove these refs using a project export. -To purge files from GitLab storage: +To purge files from a GitLab repository: 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. 1. Generate a fresh [export from the project](../settings/import_export.html#exporting-a-project-and-its-data) and download it. + This project export contains a backup copy of your repository *and* refs + we can use to purge files from your repository. 1. Decompress the backup using `tar`: @@ -134,7 +55,7 @@ To purge files from GitLab storage: This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). -1. Clone a fresh copy of the repository from the bundle: +1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell git clone --bare --mirror /path/to/project.bundle @@ -149,7 +70,7 @@ To purge files from GitLab storage: the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. - To purge all large files, the `--strip-blobs-bigger-than` option can be used: + To purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: ```shell git filter-repo --strip-blobs-bigger-than 10M @@ -236,14 +157,14 @@ This: - Runs `git gc --prune=30.minutes.ago` against the repository to remove unreferenced objects. Repacking your repository temporarily causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Unlinks any unused LFS objects attached to your project, freeing up storage space. - Recalculates the size of your repository on disk. GitLab sends an email notification with the recalculated repository size after the cleanup has completed. If the repository size does not decrease, this may be caused by loose objects being kept around because they were referenced in a Git operation that happened -in the last 30 minutes. Try re-running these steps once the repository has been +in the last 30 minutes. Try re-running these steps after the repository has been dormant for at least 30 minutes. When using repository cleanup, note: @@ -263,7 +184,7 @@ When using repository cleanup, note: Repository size limits: - Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) - on self-managed instances. **(STARTER ONLY)** + on self-managed instances. **(PREMIUM SELF)** - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 4a7f75ba1ac..efd7353c883 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -16,8 +16,8 @@ at most once every 5 minutes on GitLab.com with [the limit set by the administra There are two kinds of repository mirroring supported by GitLab: -- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(CORE)** -- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(STARTER)** +- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(FREE)** +- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(PREMIUM)** When the mirror repository is updated, all new branches, tags, and commits will be visible in the project's activity feed. @@ -37,7 +37,7 @@ 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, - and branches will be available in your GitLab instance. **(STARTER)** + and branches will be available in your GitLab instance. **(PREMIUM)** - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active GitLab repository can push its changes to the old location. @@ -47,10 +47,10 @@ The following are some possible use cases for repository mirroring: GitLab.com repository that's public, allows you to open source specific projects and contribute back to the open source community. -## Pushing to a remote repository **(CORE)** +## Pushing to a remote repository **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249) in GitLab Enterprise Edition 8.7. -> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. +> - [Moved to GitLab Free](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. > - [LFS support over HTTPS added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in 13.5 For an existing project, you can set up push mirroring as follows: @@ -205,10 +205,11 @@ If it is not working correctly a red `error` tag appears and shows the error mes 1. Fill in the **Password** field with the GitLab personal access token created on the destination GitLab instance. 1. Click the **Mirror repository** button. -## Pulling from a remote repository **(STARTER)** +## Pulling from a remote repository **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. -> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. +> - Moved to GitLab Premium in 13.9. You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. @@ -262,9 +263,10 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If - Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail up to 14 times before they will not be enqueued for update again. -### Overwrite diverged branches **(STARTER)** +### Overwrite diverged branches **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. @@ -274,7 +276,9 @@ For mirrored branches, enabling this option results in the loss of local changes To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. -### Trigger pipelines for mirror updates **(STARTER)** +### Trigger pipelines for mirror updates **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. If this option is enabled, pipelines will be triggered when branches or tags are updated from the remote repository. Depending on the activity of the remote @@ -282,9 +286,10 @@ repository, this may greatly increase the load on your CI runners. Only enable this if you know they can handle the load. CI will run using the credentials assigned when you set up pull mirroring. -### Hard failure **(STARTER)** +### Hard failure **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in GitLab 10.2. +> - Moved to GitLab Premium in 13.9. Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard failed. This will become visible in either the: @@ -295,9 +300,10 @@ failed. This will become visible in either the: When a project is hard failed, it will no longer get picked up for mirroring. You can resume the project mirroring again by [forcing an update](#forcing-an-update). -### Trigger an update using the API **(STARTER)** +### Trigger an update using the API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in GitLab 10.3. +> - Moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), @@ -305,19 +311,21 @@ updates will be pulled immediately. For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). -## Mirror only protected branches **(STARTER)** +## Mirror only protected branches **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. Based on the mirror direction that you choose, you can opt to mirror only the [protected branches](../protected_branches.md) from/to your remote repository. For pull mirroring, non-protected branches are not mirrored and can diverge. To use this option, check the **Only mirror protected branches** box when -creating a repository mirror. +creating a repository mirror. **(PREMIUM)** ## SSH authentication -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5 for Pull mirroring. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 for Push mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in GitLab 9.5 for Pull mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. SSH authentication is mutual: @@ -403,17 +411,19 @@ to generate a new key. You'll have to update the other repository with the new key to keep the mirror running. NOTE: -The generated keys are stored in the GitLab database, not in the filesystem. Therefore, +The generated keys are stored in the GitLab database, not in the file system. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. -## Forcing an update **(CORE)** +## Forcing an update **(FREE)** While mirrors are scheduled to update automatically, you can always force an update by using the update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. ![Repository mirroring force update user interface](img/repository_mirroring_force_update.png) -## Bidirectional mirroring **(STARTER)** +## Bidirectional mirroring **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring may cause conflicts. @@ -536,7 +546,9 @@ Note that this sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update and Git will complain about it. -### Mirroring with Perforce Helix via Git Fusion **(STARTER)** +### Mirroring with Perforce Helix via Git Fusion **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring should not be used as a permanent configuration. Refer to diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b9477da3937..a9e249bb8c3 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -21,8 +21,8 @@ Choose **New file** from the dropdown. Enter a filename in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field -will default to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox will appear, allowing you to start a new merge +defaults to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox displays, allowing you to start a new merge request after you commit the changes. When you are satisfied with your new file, click **Commit Changes** at the bottom. @@ -31,46 +31,45 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Shortcuts -You can use handy shortcuts when editing a file through the Web Editor, which are the same as -the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). +You can use shortcuts when editing a file through the Web Editor. It uses the same shortcuts +as the Web IDE. For details, read the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns When starting a new project, there are some common files that the new project -might need too. Therefore a message will be displayed by GitLab to make this -easy for you. +might need. GitLab displays a message to help you: ![First file for your project](img/web_editor_template_dropdown_first_file.png) -When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown will be displayed -to provide you with a template that might be suitable for your project. +When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown displays +to provide you a template that may be suitable for your project: ![MIT license selected](img/web_editor_template_dropdown_mit_license.png) -The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also -be added through a button on the project page. In the example below, the license +The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also +be added through a button on the project page. In this example, the license has already been created, which creates a link to the license itself. ![New file button](img/web_editor_template_dropdown_buttons.png) NOTE: -The **Set up CI/CD** button will not appear on an empty repository. You have to at -least add a file in order for the button to show up. +The **Set up CI/CD** button does not appear on an empty repository. For the button +to display, add a file to your repository. ## Upload a file The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs, or other file types. In +doesn't work well for binary data such as images, PDFs, or other binary file types. In this case, you need to upload a file. From a project's files page, click the '+' button to the right of the branch -selector. Choose **Upload file** from the dropdown. +selector. Choose **Upload file** from the dropdown: ![Upload file dropdown menu](img/web_editor_upload_file_dropdown.png) -Once the upload dialog pops up, there are two ways to upload your file. Either -drag and drop a file on the popup or use the **click to upload** link. A file -preview will appear once you have selected a file to upload. +After the upload dialog pops up, there are two ways to upload your file. Either +drag and drop a file on the popup or use the **click to upload** link. After you +select a file to upload, a file preview displays. Enter a commit message, choose a branch, and click **Upload file** when you are ready. @@ -100,19 +99,22 @@ There are multiple ways to create a branch from the GitLab web interface. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2808) in GitLab 8.6. -If your development workflow dictates to have an issue for every merge -request, you can quickly create a branch directly from the issue to speed the process up. -The new branch, and later its merge request, will be marked as related to this issue. -Once merged, the MR will automatically close the issue. +If your development workflow requires an issue for every merge +request, you can create a branch directly from the issue to speed the process up. +The new branch, and later its merge request, are marked as related to this issue. +Once merged, the merge request closes the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: -You won't see the **Create merge request** button if there is already a branch with the same -name or a referenced merge request or your project has an active -fork relationship. -If you would like to make this button appear, a possible workaround is to [remove your project's -fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored. This project will no longer be able to receive or send merge requests to the source project or other forks. +The **Create merge request** button doesn't display if: + +- A branch with the same name already exists. +- The branch already has a referenced merge request. +- Your project has an active fork relationship. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks. ![Create Button](img/web_editor_new_branch_from_issue_create_button_v12_6.png) @@ -120,46 +122,47 @@ This dropdown contains the options **Create merge request and branch** and **Cre ![New Branch Button](img/web_editor_new_branch_from_issue_v_12_6.png) -Once you choose one of these options, a new branch or branch and merge request -will be created based on the default -branch of your project (by default, `master`). The branch name will be based on -the title of the issue, and as a prefix, it will have its internal ID. Thus, the example -screenshot above will create a branch named +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`. +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`. When you click the **Create branch** button in an empty -repository project, GitLab automatically creates a `master` branch, commits -a blank `README.md` file to it, and creates and redirects you to a new branch -based on the issue title. -If your [project is already configured with a deployment service](../integrations/overview.md), -such as Kubernetes, GitLab takes one step further and prompts you to set up -[auto deploy](../../../topics/autodevops/stages.md#auto-deploy) -by helping you create a `.gitlab-ci.yml` file. +repository project, GitLab performs these actions: + +- Creates a `master` 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,_ + GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) + by helping you create a `.gitlab-ci.yml` file. After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly created branch, -the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the +the issue. When a merge request is created based on the newly-created branch, +the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the merge request is merged. ### Create a new branch from a project's dashboard If you want to make changes to several files before creating a new merge -request, you can create a new branch upfront. From a project's files page, -choose **New branch** from the dropdown. +request, you can create a new branch upfront. -![New branch dropdown](img/web_editor_new_branch_dropdown.png) +1. From a project's files page, choose **New branch** from the dropdown. -Enter a new **Branch name**. Optionally, change the **Create from** field -to choose which branch, tag, or commit SHA this new branch will originate from. -This field will autocomplete if you start typing an existing branch or tag. -Click **Create branch** and you will be returned to the file browser on this new -branch. + ![New branch dropdown](img/web_editor_new_branch_dropdown.png) -![New branch page](img/web_editor_new_branch_page.png) +1. Enter a new **Branch name**. +1. (Optional) Change the **Create from** field to choose which branch, tag, or + commit SHA this new branch originates from. This field autocompletes if you + start typing an existing branch or tag. +1. Click **Create branch** to return to the file browser on this new branch. + + ![New branch page](img/web_editor_new_branch_page.png) 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 `master`, 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. @@ -167,31 +170,35 @@ modify files. ## Create a new tag -Tags are useful for marking major milestones such as production releases, -release candidates, and more. You can create a tag from a branch or a commit -SHA. From a project's files page, choose **New tag** from the dropdown. +Tags help you mark major milestones such as production releases and +release candidates. You can create a tag from a branch or a commit +SHA: + +1. From a project's files page, choose **New tag** from the dropdown. -![New tag dropdown](img/web_editor_new_tag_dropdown.png) + ![New tag dropdown](img/web_editor_new_tag_dropdown.png) -Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you -would like to create this new tag. You can optionally add a message and -release notes. The release notes section supports Markdown format and you can -also upload an attachment. Click **Create tag**, and you will be taken to the tag -list page. +1. Give the tag a name such as `v1.0.0`. +1. Choose the branch or SHA from which you want to create this new tag. +1. (Optional) Add a message and release notes. The release notes section supports + Markdown format. +1. (Optional) Upload an attachment. +1. Click **Create tag**, and GitLab redirects you to the tag list page. -![New tag page](img/web_editor_new_tag_page.png) + ![New tag page](img/web_editor_new_tag_page.png) ## 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`. Enter -a new branch name in the **Target branch** field. You will notice a checkbox -appear that is labeled **Start a new merge request with these changes**. After -you commit the changes you will be taken to a new merge request form. +trigger a new merge request rather than committing directly to `master`: + +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. +1. Commit your changes, and GitLab redirects you to a new merge request form. -![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png) + ![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png) -If you'd prefer _not_ to use your primary email address for commits created +If you'd prefer to not use your primary email address for commits created through the web editor, you can choose to use another of your linked email addresses from the **User Settings > Edit Profile** page. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c99b0d91523..4e239431d02 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -260,7 +260,8 @@ For GitLab.com, it is set to 10 MB. ## Export requirements to a CSV file -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. +> - Revised CSV column headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299247) in GitLab 13.9. You can export GitLab requirements to a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification @@ -280,14 +281,29 @@ To export requirements: ### Exported CSV file format +<!-- vale gitlab.Spelling = NO --> You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, OpenOffice Calc, or Google Sheets. +<!-- vale gitlab.Spelling = YES --> -The exported CSV file contains the following columns: +The exported CSV file contains the following headers: -- Requirement ID -- Title -- Description -- Author Username -- Latest Test Report State -- Latest Test Report Created At (UTC) +- In GitLab 13.8: + + - Requirement ID + - Title + - Description + - Author Username + - Latest Test Report State + - Latest Test Report Created At (UTC) + +- In GitLab 13.9 and later: + + - Requirement ID + - Title + - Description + - Author + - Author Username + - Created At (UTC) + - State + - State Updated At (UTC) diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md deleted file mode 100644 index d9440e8deea..00000000000 --- a/doc/user/project/security_dashboard.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../application_security/security_dashboard/index.md' ---- - -This document was moved to [another location](../application_security/security_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 76156690fe7..7c66f078770 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -4,11 +4,11 @@ group: Certify 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 --- -# Service Desk **(CORE)** +# Service Desk **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.2. Service Desk is a module that allows your team to connect with any external party through email, without any external tools. @@ -34,7 +34,7 @@ It provides a unique email address for end users to create issues in a project. Follow-up notes can be sent either through the GitLab interface or by email. End users only see the thread through email. -For instance, let's assume you develop a game for iOS or Android. +For example, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed with GitLab CI/CD. @@ -91,39 +91,59 @@ Service Desk is now enabled for this project! You should be able to access it fr > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.2. An email is sent to the author when: - A user submits a new issue using Service Desk. - A new note is created on a Service Desk issue. -The body of these email messages can be customized by using templates. To create a new customized template, -create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` -directory in your repository. Commit and push to your default branch. +You can customize the body of these email messages with templates. +Save your templates in the `.gitlab/service_desk_templates/` +directory in your repository. + +With Service Desk, you can use templates for: + +- [Thank you emails](#thank-you-email) +- [New note emails](#new-note-email) +- [New Service Desk issues](#new-service-desk-issues) #### Thank you email -The **Thank you email** is the email sent to a user after they submit an issue. -The filename of the template has to be `thank_you.md`. -There are a few placeholders you can use which are automatically replaced in the email: +When a user submits an issue through Service Desk, GitLab sends a **thank you email**. +You must name the template file `thank_you.md`. + +You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID -As the Service Desk issues are created as confidential (only project members can see them) -the response email does not provide the issue link. +Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), +the response email does not contain the issue link. #### New note email -When a user-submitted issue receives a new comment, GitLab sends a **New note email** -to the user. The filename of this template must be `new_note.md`, and you can -use these placeholders in the email: +When a user-submitted issue receives a new comment, GitLab sends a **new note email**. +You must name the template file `new_note.md`. + +You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID - `%{NOTE_TEXT}`: note text +#### New Service Desk issues + +You can select one [issue description template](description_templates.md#creating-issue-templates) +**per project** to be appended to every new Service Desk issue's description. +Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. + +To use a custom issue template with Service Desk, in your project: + +1. [Create a description template](description_templates.md#creating-issue-templates) +1. Go to **Settings > General > Service Desk**. +1. From the dropdown **Template to append to all Service Desk issues**, select your template. + ### Using custom email display name > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 27727890383..6f230f1798a 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -18,7 +18,7 @@ The **GitLab import/export** button is displayed if the project import option is See also: - [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(CORE ONLY)** +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** - [Group import/export](../../group/settings/import_export.md) - [Group import/export API](../../../api/group_import_export.md) @@ -180,14 +180,14 @@ all imported projects are given the visibility of `Private`. NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ### Project import status You can query an import through the [Project import/export API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. -### Import large projects **(CORE ONLY)** +### Import large projects **(FREE SELF)** If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 26ef5e2260a..aa41f1c0233 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -40,6 +40,26 @@ You can select a framework label to identify that your project has certain compl NOTE: Compliance framework labels do not affect your project settings. +#### Custom compliance frameworks + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) 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-custom-compliance-frameworks). **(PREMIUM ONLY)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +GitLab 13.8 introduces custom compliance frameworks at the group-level. A group owner can create a compliance framework label +and assign it to any number of projects within that group or sub-groups. When this feature is enabled, projects can only +be assigned compliance framework labels that already exist within that group. + +If existing [Compliance frameworks](#compliance-framework) are not sufficient, you can now create +your own. + +New compliance framework labels can be created and updated using GraphQL. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -120,7 +140,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/merge_request_approvals.md). **(STARTER)** +- Enable [merge request approvals](../merge_requests/merge_request_approvals.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 [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) @@ -128,7 +148,7 @@ Set up your project's merge request settings: ![project's merge request settings](img/merge_requests_settings.png) -### Service Desk **(STARTER)** +### Service Desk Enable [Service Desk](../service_desk.md) for your project to offer customer support. @@ -245,8 +265,8 @@ To delete a project: 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 or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group administrators can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group +- 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#enabling-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). @@ -299,3 +319,22 @@ Add the URL of a Jaeger server to allow your users to [easily access the Jaeger [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). + +### Enable or disable custom compliance frameworks **(PREMIUM ONLY)** + +Enabling or disabling custom compliance frameworks 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(:ff_custom_compliance_frameworks) +``` + +To disable it: + +```ruby +Feature.disable(:ff_custom_compliance_frameworks) +``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 39de9ab9ca2..590f549577e 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -8,13 +8,11 @@ type: reference, howto # Project access tokens NOTE: -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). +Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. -> - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. -> - It's recommended for production use. -> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5 for paid groups only. +> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md deleted file mode 100644 index 5844861c91e..00000000000 --- a/doc/user/project/slash_commands.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'quick_actions.md' ---- - -This document was moved to [user/project/quick_actions.md](quick_actions.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 07f122a7828..e4916d524e6 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -6,11 +6,11 @@ type: reference, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- -# Static Site Editor **(CORE)** +# Static Site Editor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. -> - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. +> - Non-Markdown content blocks not editable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. > - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. Static Site Editor (SSE) enables users to edit content on static websites without @@ -23,8 +23,8 @@ and submit the changes for review. The Static Site Editor allows collaborators to submit changes to static site files seamlessly. For example: -- Non-technical collaborators can easily edit a page directly from the browser; - they don't need to know Git and the details of your project to be able to contribute. +- Non-technical collaborators can edit a page directly from the browser. + They don't need to know Git and the details of your project to contribute. - Recently hired team members can quickly edit content. - Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. @@ -68,7 +68,7 @@ The editor can then navigate to the merge request to assign it to a colleague fo ## Set up your project First, set up the project. Once done, you can use the Static Site Editor to -easily [edit your content](#edit-content). +[edit your content](#edit-content). 1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) @@ -101,7 +101,7 @@ To edit a file: wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request that will be submitted +1. (Optional) Adjust the default title and description of the merge request, to submit with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. @@ -154,9 +154,9 @@ so you can verify the correct image is included and there aren't any references You can embed YouTube videos on the WYSIWYG mode by clicking the video icon (**{live-preview}**). The following URL/ID formats are supported: -- YouTube watch URL (e.g. `https://www.youtube.com/watch?v=0t1DgySidms`) -- YouTube embed URL (e.g. `https://www.youtube.com/embed/0t1DgySidms`) -- YouTube video ID (e.g. `0t1DgySidms`) +- **YouTube watch URLs**: `https://www.youtube.com/watch?v=0t1DgySidms` +- **YouTube embed URLs**: `https://www.youtube.com/embed/0t1DgySidms` +- **YouTube video IDs**: `0t1DgySidms` ### Front matter @@ -164,13 +164,13 @@ The following URL/ID formats are supported: > - Ability to edit page front matter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235921) in GitLab 13.5. Front matter is a flexible and convenient way to define page-specific variables in data files -intended to be parsed by a static site generator. It is commonly used for setting a page's -title, layout template, or author, but can be used to pass any kind of metadata to the +intended to be parsed by a static site generator. Use it to set a page's +title, layout template, or author. You can also pass any kind of metadata to the generator as the page renders out to HTML. Included at the very top of each data file, the -front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. +front matter is often formatted as YAML or JSON, and requires consistent and accurate syntax. To edit the front matter from the Static Site Editor you can use the GitLab regular file editor, -the Web IDE, or easily update the data directly from the WYSIWYG editor: +the Web IDE, or update the data directly from the WYSIWYG editor: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you have on the page's front matter. The form is populated with the current data: @@ -181,10 +181,16 @@ the Web IDE, or easily update the data directly from the WYSIWYG editor: 1. When you're done, click **Submit changes...**. 1. Describe your changes (add a commit message). 1. Click **Submit changes**. -1. Click **View merge request** and GitLab will take you there. +1. Click **View merge request** to view it. -Note that support for adding new attributes to the page's front matter from the form is not supported -yet. You can do so by editing the file locally, through the GitLab regular file editor, or through the Web IDE. Once added, the form will load the new fields. +Adding new attributes to the page's front matter from the form is not supported. +To add new attributes: + +- Edit the file locally +- Edit the file with the GitLab regular file editor. +- Edit the file with the Web IDE. + +After adding an attribute, the form loads the new fields. ## Configuration files @@ -206,8 +212,8 @@ use to customize behavior of the Static Site Editor (SSE). If the file does not default values which support a default Middleman project configuration are used. The [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) project template generates a file pre-populated with these defaults. -To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries -(described in the table below) according to what works best for your project (respecting YAML syntax). +To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries, +according to your project's needs. Make sure to respect YAML syntax. After the table, see an [example of the SSE configuration file](#gitlabstatic-site-editoryml-example). @@ -224,8 +230,9 @@ image_upload_path: 'source/images' # Relative path to the project's root. Don't ### Static Site Generator configuration The Static Site Editor uses Middleman's configuration file, `data/config.yml` -to customize the behavior of the project itself and to control the **Edit this -page** button, rendered through the file [`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). +to customize the behavior of the project itself. This file also controls the +**Edit this page** button, rendered through the file +[`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). To [configure the project template to your own project](#set-up-your-project), you must replace the `<username>` and `<project-name>` in the `data/config.yml` @@ -236,7 +243,7 @@ the Static Site Editor may use different configuration files or approaches. ## Using Other Static Site Generators -Although Middleman is the only Static Site Generator currently officially supported +Although Middleman is the only Static Site Generator officially supported by the Static Site Editor, you can configure your project's build and deployment to use a different Static Site Generator. In this case, use the Middleman layout as an example, and follow a similar approach to properly render an **Edit this page** diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md deleted file mode 100644 index 513c410a6f9..00000000000 --- a/doc/user/project/status_page/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/status_page.md' ---- - -This document was moved to [status_page.md](../../../operations/incident_management/status_page.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index c94795578ef..2b0ca38c57c 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -81,7 +81,7 @@ The following time units are available: Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. -### Limit displayed units to hours **(CORE ONLY)** +### Limit displayed units to hours **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index af8e78afb28..69f58dad1dc 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,10 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Web IDE **(CORE)** +# Web IDE **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. The Web IDE editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. @@ -22,11 +22,11 @@ and from merge requests. ## File finder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Free](https://about.gitlab.com/pricing/) 10.8. The file finder allows you to quickly open files in the current branch by searching for fragments of the file path. The file finder is launched using the keyboard shortcut -<kbd>Cmd</kbd>+<kbd>p</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> +<kbd>Command</kbd>+<kbd>p</kbd>, <kbd>Control</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> (when editor is not in focus). Type the filename or file path fragments to start seeing results. @@ -102,7 +102,7 @@ based on the [JSON Schema Store](https://www.schemastore.org/json/). The Web IDE has validation for certain files built in. This feature is only supported for the `*.gitlab-ci.yml` files. -#### Enable or disable validation based on predefined schemas **(CORE ONLY)** +#### Enable or disable validation based on predefined schemas **(FREE SELF)** Validation based on predefined schemas is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default** for self-managed instances, @@ -154,7 +154,7 @@ Each schema entry supports two properties: ## Configure the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -174,7 +174,7 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. > - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. > - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. @@ -202,7 +202,7 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed @@ -215,7 +215,7 @@ left. ## Switching merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. To switch between your authored and assigned merge requests, click the dropdown in the top of the sidebar to open a list of merge requests. You need to commit or discard all your changes before switching to a different merge @@ -223,7 +223,7 @@ request. ## Switching branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. To switch between branches of the current project repository, click the dropdown in the top of the sidebar to open a list of branches. @@ -232,8 +232,8 @@ different branch. ## Markdown editing -> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Core](https://about.gitlab.com/pricing/) 10.7. -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. +> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. When you edit Markdown files in the Web IDE, you can preview your changes by clicking the **Preview Markdown** tab above the file editor. The Markdown preview @@ -246,7 +246,7 @@ added to the filename. ## Live Preview -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. @@ -285,7 +285,7 @@ below. ## Interactive Web Terminals for the Web IDE > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -307,7 +307,7 @@ to work: This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. - If you are using a reverse proxy with your GitLab instance, web terminals need to be - [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE ONLY)** + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE SELF)** If you have the terminal open and the job has finished with its tasks, the terminal blocks the job from finishing for the duration configured in @@ -389,7 +389,7 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Free in 13.1. File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 779179a6665..087a9069c7c 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,11 +1,11 @@ --- stage: Create -group: Knowledge +group: Editor info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, how-to --- -# Wiki **(CORE)** +# Wiki **(FREE)** A separate system for documentation called Wiki, is built right into each GitLab project. It is enabled by default on all new projects and you can find |