diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
| commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
| tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc/user/project | |
| parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) | |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc/user/project')
205 files changed, 2348 insertions, 2083 deletions
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 1aa040c9cb8..8d8ff942d05 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -3,10 +3,12 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference -description: "Autocomplete chars in Markdown fields." +description: "Autocomplete characters in Markdown fields." --- -# Autocomplete characters +# Autocomplete characters **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36705) in GitLab 13.9: you can search using the full name in user autocomplete. The autocomplete characters provide a quick way of entering field values into Markdown fields. When you start typing a word in a Markdown field with one of @@ -57,4 +59,7 @@ 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. - + + +You can also search across the full name to find a user. +To find `Rosy Grant`, even if their username is for example `hunter2`, you can type their full name without spaces like `@rosygrant`. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index f7bb88c33aa..7e6bba30001 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Badges +# Badges **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. 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..d7e8133f9ad 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -14,27 +14,28 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. -NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## Bulk edit issues at the project level -NOTE: -You need a permission level of [Reporter or higher](../permissions.md) to manage issues. +> - 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. + +Users with permission level of [Reporter or higher](../permissions.md) can manage issues. 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: @@ -46,8 +47,7 @@ To update multiple project issues at the same time: ## Bulk edit merge requests at the project level -NOTE: -You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. +Users with permission level of [Developer or higher](../permissions.md) can manage merge requests. When bulk editing merge requests in a project, you can edit the following attributes: 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..eb6b8302667 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 **(FREE)** 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..af3a17dc60c 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 **(FREE)** 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..718c60ccf0e 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 **(FREE)** 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 @@ -387,3 +387,13 @@ If you encounter this error while adding a Kubernetes cluster, ensure you're properly pasting the service token. Some shells may add a line break to the service token, making it invalid. Ensure that there are no line breaks by pasting your token into an editor and removing any additional spaces. + +You may also experience this error if your certificate is not valid. To check that your certificate's +subject alternative names contain the correct domain for your cluster's API, run this: + +```shell +echo | openssl s_client -showcerts -connect kubernetes.example.com:443 2>/dev/null | +openssl x509 -inform pem -noout -text +``` + +Note that the `-connect` argument expects a `host:port` combination. For example, `https://kubernetes.example.com` would be `kubernetes.example.com:443`. 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..d3d434762ab 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. @@ -86,7 +87,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster @@ -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 @@ -239,7 +289,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#custom-environment-variables) + using [environment variables](../../../ci/variables/README.md#custom-cicd-variables) before you can interact with the cluster from your jobs. ### Deployment variables @@ -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 -[deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment to deployment jobs, which are jobs that have +The Kubernetes cluster integration exposes these +[deployment variables](../../../ci/variables/README.md#deployment-variables) in the +GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md#defining-environments). | Variable | Description | @@ -303,11 +353,11 @@ 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 -[Protected Environments](../../../ci/environments/protected_environments.md), +[protected environments](../../../ci/environments/protected_environments.md), combined with either - a GitLab-managed cluster and namespace per environment, @@ -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/).  diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 8572ab850e4..7f344349984 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 **(FREE)** 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..192a7c7cd39 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 **(FREE)** GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. @@ -25,7 +25,7 @@ Additionally, in the [How To section](#how-to), you can read about different use - Working with secrets. - Setting up CORS. -Alternatively, you can quickly [create a new project with a template](../../../../gitlab-basics/create-project.md#project-templates). The [`Serverless Framework/JS` template](https://gitlab.com/gitlab-org/project-templates/serverless-framework/) already includes all parts described below. +Alternatively, you can quickly [create a new project with a template](../../working_with_projects.md#create-a-project). The [`Serverless Framework/JS` template](https://gitlab.com/gitlab-org/project-templates/serverless-framework/) already includes all parts described below. ### Example @@ -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 @@ -290,7 +290,7 @@ The example code is available: - As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). -You can also use a [template](../../../../gitlab-basics/create-project.md#project-templates) +You can also use a [template](../../working_with_projects.md#project-templates) (based on the version with tests and secret variables) from within the GitLab UI (see the `Serverless Framework/JS` template). diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 043c5e4ca79..c7ed8d6d2a5 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 **(FREE)** > Introduced in GitLab 11.5. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 19dc3588162..0e8c1bf8f4d 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Intelligence +# Code Intelligence **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 63ea84e42c9..3135aa78719 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:  -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): -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 +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) +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:  @@ -142,9 +145,9 @@ Code Owners:  -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:  -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..a45c3d26f1a 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Keys +# 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. @@ -21,7 +21,7 @@ There are two types of deploy keys: ## Key details on deploy keys -Deploy Keys allow a remote machine (VM, physical, and so on) to access a GitLab +Deploy keys allow a remote machine (VM, physical, and so on) to access a GitLab repository with just a few steps. If you want a remote machine to interact with a GitLab repository in automation, it's a simple solution. @@ -35,7 +35,7 @@ If this security implication is a concern for your organization, [Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more security control. -## Deploy Keys Permissions +## Deploy keys permissions You can choose the access level of a deploy key when you enable it on a project: @@ -72,7 +72,7 @@ help you access a repository, but there are some notables differences between th on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). - You need an SSH key pair to use deploy keys, but not deploy tokens. -## How to enable Deploy Keys +## How to enable deploy keys ### Project deploy keys @@ -80,17 +80,17 @@ help you access a repository, but there are some notables differences between th 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. 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: +There are three lists of project deploy keys: - Enabled deploy keys - Privately accessible deploy keys - Public accessible deploy keys - + After you add a key, it's enabled for this project by default and it appears in the **Enabled deploy keys** tab. @@ -129,7 +129,7 @@ Instance administrators can add public deploy keys: if the key gives access to a SaaS CI/CD instance, use the name of that service in the key name if that is all the key is used for. - + After adding a key, it's available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. @@ -153,7 +153,7 @@ until a project maintainer chooses to make use of it. ## Troubleshooting -### Deploy Key cannot push to a protected branch +### Deploy key cannot push to a protected branch If the owner of this deploy key doesn't have access to a [protected branch](../protected_branches.md), then this deploy key doesn't have access to 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..c56470ee07a 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,16 +6,11 @@ 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. - 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 +23,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 +37,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 +47,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 +80,16 @@ 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`.  -## Setting a default template for merge requests and issues **(STARTER)** +## Setting a default template for merge requests and issues **(PREMIUM)** -> - 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. +> - Moved to GitLab Premium in 13.9. -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 +112,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 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) -(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/git_attributes.md b/doc/user/project/git_attributes.md index 459abea455b..2806f6e48d1 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Git Attributes +# Git Attributes **(FREE)** GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting 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..c914c90c923 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -5,24 +5,30 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Syntax Highlighting +# Syntax Highlighting **(FREE)** -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/img/optional_code_owners_sections_v13_8.png b/doc/user/project/img/optional_code_owners_sections_v13_8.png Binary files differindex 7a5a2fab6e3..50916466226 100644 --- a/doc/user/project/img/optional_code_owners_sections_v13_8.png +++ b/doc/user/project/img/optional_code_owners_sections_v13_8.png diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png Binary files differdeleted file mode 100644 index fdf8fa024c3..00000000000 --- a/doc/user/project/img/service_desk_nav_item.png +++ /dev/null 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**:  + <!-- vale gitlab.Spelling = YES --> -1. Use the "GitHub" button to connect your repositories. +1. Use the **GitHub** button to connect your repositories.  -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**.  diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 754c3e31799..f6ed53763dd 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -74,3 +74,25 @@ In the event of merging two GitLab instances together (for example, both instanc refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. + +## Project aliases **(PREMIUM SELF)** + +> [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 +they are a lot. It reduces the risk of changing significant number of Git URLs in +a large number of systems. + +GitLab provides a functionality to help with this. In GitLab, repositories are +usually accessed with a namespace and project name. It is also possible to access +them via a project alias. This feature is only available on Git over SSH. + +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. + +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`). 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 -->  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..a8ab1cbbb63 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -5,63 +5,59 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Projects +# Projects **(FREE)** -In GitLab, you can create projects for hosting -your codebase, use it as an issue tracker, collaborate on code, and continuously -build, test, and deploy your app with built-in GitLab CI/CD. +In GitLab, you can create projects to host +your codebase. You can also use projects to track issues, plan work, +collaborate on code, and continuously build, test, and use +built-in CI/CD to deploy your app. -Your projects can be [available](../../public_access/public_access.md) -publicly, internally, or privately, at your choice. GitLab does not limit -the number of private projects you create. +Projects can be available [publicly, internally, or privately](../../public_access/public_access.md). +GitLab does not limit the number of private projects you can create. ## Project features -When you create a project in GitLab, you'll have access to a large number of -[features](https://about.gitlab.com/features/): +Projects include the following [features](https://about.gitlab.com/features/): **Repositories:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within 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 - integrated platform - - [Branches](repository/branches/index.md): use Git branching strategies to - collaborate on code +- [Issue tracker](issues/index.md): Discuss implementations with your team. + - [Issue Boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. +- [Repositories](repository/index.md): Host your code in a fully-integrated platform. + - [Branches](repository/branches/index.md): Use Git branching strategies to + collaborate on code. - [Protected branches](protected_branches.md): Prevent collaborators - from messing with history or pushing code without review - - [Protected tags](protected_tags.md): Control over who has - permission to create tags, and prevent accidental update or deletion + from changing history or pushing code without review. + - [Protected tags](protected_tags.md): Control who has + permission to create tags and prevent accidental updates or deletions. - [Repository mirroring](repository/repository_mirroring.md) - - [Signing commits](repository/gpg_signed_commits/index.md): use GPG to sign your commits - - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. + - [Signing commits](repository/gpg_signed_commits/index.md): Use GNU Privacy Guard (GPG) to sign your commits. + - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a vulnerability in your project. **Issues and merge requests:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within 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 +- [Issue tracker](issues/index.md): Discuss implementations with your team. + - [Issue Boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. +- [Merge Requests](merge_requests/index.md): Apply a 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)** - - [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 - of the changes proposed in a merge request in a per-branch basis -- [Labels](labels.md): Organize issues and merge requests by labels -- [Time Tracking](time_tracking.md): Track estimate time - and time spent on - the conclusion of an issue or merge request -- [Milestones](milestones/index.md): Work towards a target date + implementing a change. + - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. + - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results + of the changes proposed in a merge request. +- [Labels](labels.md): Organize issues and merge requests by labels. +- [Time Tracking](time_tracking.md): Track time estimated and + spent on issues and merge requests. +- [Milestones](milestones/index.md): Work toward a target date. - [Description templates](description_templates.md): Define context-specific - templates for issue and merge request description fields for your project -- [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for - common actions on issues or merge requests + templates for issue and merge request description fields. +- [Slash commands (quick actions)](quick_actions.md): Create text shortcuts for + common actions. - [Autocomplete characters](autocomplete_characters.md): Autocomplete references to users, groups, issues, merge requests, and other GitLab elements. @@ -69,109 +65,55 @@ When you create a project in GitLab, you'll have access to a large number of **GitLab CI/CD:** -- [GitLab CI/CD](../../ci/README.md): the GitLab built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool +- [GitLab CI/CD](../../ci/README.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. - [Container Registry](../packages/container_registry/index.md): Build and push Docker - images out-of-the-box + images. - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD - to automatically set up your app's deployment + to automatically set up your app's deployment. - [Enable and disable GitLab CI/CD](../../ci/enable_or_disable_ci.md) - [Pipelines](../../ci/pipelines/index.md): Configure and visualize - your GitLab CI/CD pipelines from the UI + your GitLab CI/CD pipelines from the UI. - [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline - to start at a chosen time + to start at a chosen time. - [Pipeline Graphs](../../ci/pipelines/index.md#visualize-pipelines): View your - entire pipeline from the UI + pipeline from the UI. - [Job artifacts](../../ci/pipelines/job_artifacts.md): Define, - browse, and download job artifacts - - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), - timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project - with a Kubernetes cluster - - [Feature Flags](../../operations/feature_flags.md): Feature flags allow you to ship a project in - different flavors by dynamically toggling certain functionality **(PREMIUM)** + browse, and download job artifacts. + - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (how jobs fetch your repository), + timeout (the maximum amount of time a job can run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline visibility, and more. + - [Kubernetes cluster integration](clusters/index.md): Connect your GitLab project + with a Kubernetes cluster. + - [Feature Flags](../../operations/feature_flags.md): Ship different features + by dynamically toggling functionality. **(PREMIUM)** - [GitLab Pages](pages/index.md): Build, test, and deploy your static - website with GitLab Pages + website. **Other features:** -- [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. -- [Snippets](../snippets.md): store, share and collaborate on code snippets. -- [Value Stream Analytics](../analytics/value_stream_analytics.md): review your development lifecycle. -- [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** -- [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** -- [Syntax highlighting](highlighting.md): an alternative to customize - your code blocks, overriding the GitLab default choice of language. -- [Badges](badges.md): badges for the project overview. -- [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of - the source, build output, other metadata, and other artifacts +- [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki. +- [Snippets](../snippets.md): Store, share and collaborate on code snippets. +- [Value Stream Analytics](../analytics/value_stream_analytics.md): Review your development lifecycle. +- [Insights](insights/index.md): Configure the insights that matter for your projects. **(ULTIMATE)** +- [Security Dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** +- [Syntax highlighting](highlighting.md): Customize + your code blocks, overriding the default language choice. +- [Badges](badges.md): Add an image to the project overview. +- [Releases](releases/index.md): Take a snapshot of + the source, build output, metadata, and artifacts associated with a released version of your code. -- [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)** -- [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)** -- [Static Site Editor](static_site_editor/index.md): quickly edit content on static websites without prior knowledge of the codebase or Git commands. -- [Code Intelligence](code_intelligence.md): code navigation features. +- [Package Registry](../packages/package_registry/index.md): Publish and install packages. +- [Code owners](code_owners.md): Specify code owners for specific 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): Create criteria to check your products against. **(ULTIMATE)** +- [Static Site Editor](static_site_editor/index.md): Edit content on static websites without prior knowledge of the codebase or Git commands. +- [Code Intelligence](code_intelligence.md): Navigate code. -### Project integrations +## Project integrations [Integrate your project](integrations/index.md) with Jira, Mattermost, Kubernetes, Slack, and a lot more. -## New project - -Learn how to [create a new project](../../gitlab-basics/create-project.md) in GitLab. - -### Fork a project - -You can [fork a project](repository/forking_workflow.md) in order to: - -- Collaborate on code by forking a project and creating a merge request - from your fork to the upstream project -- Fork a sample project to work on the top of that - -### Star a project - -You can star a project to make it easier to find projects you frequently use. -The number of stars a project has can indicate its popularity. - -To star a project: - -1. Go to the home page of the project you want to star. -1. In the upper right corner of the page, click **Star**. - -To view your starred projects: - -1. Click **Projects** in the navigation bar. -1. Click **Starred Projects**. -1. GitLab displays information about your starred projects, including: - - - Project description, including name, description, and icon - - Number of times this project has been starred - - Number of times this project has been forked - - Number of open merge requests - - Number of open issues - -### Explore projects - -You can explore other popular projects available on GitLab. To explore projects: - -1. Click **Projects** in the navigation bar. -1. Click **Explore Projects**. - -GitLab displays a list of projects, sorted by last updated date. To view -projects with the most [stars](#star-a-project), click **Most stars**. To view -projects with the largest number of comments in the past month, click **Trending**. - -## Project settings - -Set the project's visibility level and the access levels to its various pages -and perform actions like archiving, renaming or transferring a project. - -Read through the documentation on [project settings](settings/index.md). - ## Import or export a project - [Import a project](import/index.md) from: @@ -182,64 +124,6 @@ Read through the documentation on [project settings](settings/index.md). - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) -## Delete a project - -To delete a project, first navigate to the home page for that project. - -1. Navigate to **Settings > General**. -1. Expand the **Advanced** section. -1. Scroll down to the **Delete project** section. -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). - -## CI/CD for external repositories **(PREMIUM)** - -Instead of importing a repository directly to GitLab, you can connect your repository -as a CI/CD project. - -Read through the documentation on [CI/CD for external repositories](../../ci/ci_cd_for_external_repos/index.md). - -## Project members - -Learn how to [add members to your projects](members/index.md). - -## Project activity - -To view the activity of a project, navigate to **Project overview > Activity**. -From there, you can click on the tabs to see **All** the activity, or see it -filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, -**Team**, and **Wiki**. - -### Leave a project - -**Leave project** will only display 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. - -## Project's landing page - -The project's landing page shows different information depending on -the project's visibility settings and user permissions. - -For public projects, and to members of internal and private projects -with [permissions to view the project's code](../permissions.md#project-members-permissions): - -- The content of a - [`README` or an index file](repository/#repository-readme-and-index-files) - is displayed (if any), followed by the list of directories within 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. - -For users without permissions to view the project's code: - -- The wiki homepage is displayed, if any. -- The list of issues within the project is displayed. - ## GitLab Workflow - VS Code extension To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate @@ -248,142 +132,6 @@ the [VS Code](https://code.visualstudio.com/) editor with GitLab through the To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). -## Redirects when changing repository paths - -When a repository path changes, it is essential to smoothly transition from the -old location to the new one. GitLab provides two kinds of redirects: the web UI -and Git push/pull redirects. - -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 - 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 - 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 - 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 - another group, user or project. - -## Use your project as a Go package - -Any project can be used as a Go package. GitLab responds correctly to `go get` -and `godoc.org` discovery requests, including the -[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and -[`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 -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 -private projects in subgroups to the first two segments, causing `go get` to -fail. - -GitLab implements its own Go proxy. This feature must be enabled by an -administrator and requires additional configuration. See [GitLab Go -Proxy](../packages/go_proxy/index.md). - -### Disable Go module features for private projects - -In Go 1.12 and later, Go queries module proxies and checksum databases in the -process of [fetching a -module](../../development/go_guide/dependencies.md#fetching). This can be -selectively disabled with `GOPRIVATE` (disable both), -[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy -queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) -(disable checksum queries). - -`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 -databases if the module name or a prefix of it appears in `GONOPRIVATE` or -`GONOSUMDB`. - -### Authenticate Go requests - -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 -through Git. - -For example: - -```plaintext -machine gitlab.example.com -login <gitlab_user_name> -password <personal_access_token> -``` - -NOTE: -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): - -```shell -# 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: -git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" -``` - -## Access project page with project ID - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. - -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)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 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 -they are a lot. It reduces the risk of changing significant number of Git URLs in -a large number of systems. - -GitLab provides a functionality to help with this. In GitLab, repositories are -usually accessed with a namespace and project name. It is also possible to access -them via a project alias. This feature is only available on Git over SSH. - -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 -`git clone git@gitlab.com:gitlab-org/gitlab.git`). - -## Project activity analytics overview **(ULTIMATE ONLY)** - -> [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). - -Project details include the following analytics: - -- Deployment Frequency - -For more information, see [Project Analytics API](../../api/project_analytics.md). - ## Project APIs There are numerous [APIs](../../api/README.md) to use with your projects: @@ -404,4 +152,14 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Traffic](../../api/project_statistics.md) - [Variables](../../api/project_level_variables.md) - [Aliases](../../api/project_aliases.md) -- [Analytics](../../api/project_analytics.md) +- [DORA4 Analytics](../../api/dora4_project_analytics.md) + +## DORA4 analytics overview **(ULTIMATE ONLY)** + +> [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). + +Project details include the following analytics: + +- Deployment Frequency + +For more information, see [DORA4 Project Analytics API](../../api/dora4_project_analytics.md). diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 30a21dd7f66..fb9314f7504 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -50,7 +50,7 @@ service in GitLab. 1. Enter the build key from your Bamboo build plan. Build keys are typically made up from the Project Key and Plan Key that are set on project/plan creation and separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all - uppercase identifier that is unique. When viewing a plan within Bamboo, the + uppercase identifier that is unique. When viewing a plan in Bamboo, the build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. 1. If necessary, enter username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require @@ -60,8 +60,12 @@ service in GitLab. ## Troubleshooting +### Builds not triggered + If builds are not triggered, ensure you entered the right GitLab IP address in Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. -NOTE: -Starting with GitLab 8.14.0, builds are triggered on push events. +### Advanced Atlassian Bamboo features not available in GitLab UI + +Advanced Atlassian Bamboo features are not compatible with GitLab. These features +include, but are not limited to, the ability to watch the build logs from the GitLab UI. 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..0470869c4f7 --- /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..5857c3da803 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,57 +6,83 @@ 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)** +- Create a Jira issue from a vulnerability. **(ULTIMATE)** -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:** > @@ -65,37 +91,52 @@ In order to enable the Jira service in GitLab, you need to first configure the p > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable the Jira integration in a project, navigate to the -[Integrations page](overview.md#accessing-integrations) and click -the **Jira** service. +To enable the Jira integration in a project: + +1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the + **Jira** service. + +1. Select **Enable integration**. + +1. Select **Trigger** actions. + This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, + should link the Jira issue back to that source commit/MR and transition the Jira issue, if + indicated. + +1. To include a comment on the Jira issue when the above reference is made in GitLab, select + **Enable comments**. + + 1. Select the **Comment detail**: **Standard** or **All details**. -Select **Enable integration**. +1. Enter the further details on the page as described in the following table. -Select a **Trigger** action. This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, should link the Jira issue back to that source commit/MR and transition the Jira issue, if indicated. + | Field | Description | + | ----- | ----------- | + | `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 include a comment on the Jira issue when the above reference is made in GitLab, check **Enable comments**. +1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and + enter a Jira project key. **(PREMIUM)** -Enter the further details on the page as described in the following table. + You can only display issues from a single Jira project within a given GitLab project. -| 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**. | -| `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`. | + WARNING: + If you enable Jira issues with the setting above, all users that have access to this GitLab project + are able to view all issues from the specified Jira project. -To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** +1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. -You can only display issues from a single Jira project within a given GitLab project. + 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. -WARNING: -If you enable Jira issues with the setting above, all users that have access to this GitLab project -are able to view all issues from the specified Jira project. +1. To verify the Jira connection is working, select **Test settings**. -When you have configured all settings, click **Test settings and save changes**. +1. Select **Save changes**. -Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project. +Your GitLab project can now interact with all Jira projects in your instance and the project now +displays a Jira link that opens the Jira project. #### Obtaining a transition ID @@ -107,19 +148,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 +242,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.  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**. - +  - +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). +  -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..6a1529f001a 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. | @@ -33,3 +53,4 @@ The following Jira integrations allow different types of cross-referencing betwe | Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | | Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | | Display a list of Jira issues | Yes **(PREMIUM)** | No | +| Create a Jira issue from a vulnerability or finding **(ULTIMATE)** | Yes | No | 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**.  -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.  -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**.  - 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`.  - 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.  -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`.  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. | - + diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index c391877be20..b22a7c0295e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -13,7 +13,7 @@ functionality to GitLab. ## Accessing integrations You can find the available integrations under your project's -**Settings ➔ Integrations** page. +**Settings > Integrations** page. There are more than 20 integrations to integrate with. Click on the one that you want to configure. @@ -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 1507cea348a..c307fd8d628 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.  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). @@ -191,12 +207,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 @@ -223,7 +240,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..998300e255f 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. @@ -35,6 +35,6 @@ In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the -[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-environment-variables), +[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-cicd-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#exporters). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ae330158a58..2a6bc810f71 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. @@ -40,7 +40,7 @@ Prometheus needs to be deployed into the cluster and configured properly in orde In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. -Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. +Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. ## Displaying Canary metrics **(PREMIUM)** 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/services_templates.md b/doc/user/project/integrations/services_templates.md index a60af93a899..7507792bb02 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Service templates +WARNING: +Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +in GitLab 14.0. Use [project integration management](#central-administration-of-project-integrations) instead. + Using a service template, GitLab administrators can: - Provide default values for configuring integrations when creating new projects. 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..0cf01adef13 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: @@ -1029,6 +1029,9 @@ X-Gitlab-Event: Wiki Page Hook ### Pipeline events +In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) +and later, the pipeline webhook returns only the latest jobs. + Triggered on status change of Pipeline. **Request Header**: @@ -1151,10 +1154,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 +1191,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 +1221,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 +1324,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 +1488,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..e4f42b97b84 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,9 +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)** - -> [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). +# Issue Boards **(FREE)** The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. @@ -38,10 +36,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. @@ -53,11 +50,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 group are available in [GitLab Premium](https://about.gitlab.com/pricing/). +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. +> - Multiple issue boards per group are available in GitLab Premium. -Multiple issue boards allow for more than one issue board for a given project **(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,13 +224,13 @@ 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)** +### Configurable issue boards **(PREMIUM)** -> - [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in GitLab 10.2. > - Setting current iteration as scope [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196804) in GitLab 13.8. +> - Moved to GitLab Premium in 13.9. An issue board can be associated with a [milestone](milestones/index.md#milestones), [labels](labels.md), assignee, weight, and current [iteration](../group/iterations/index.md), @@ -257,14 +253,15 @@ 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 GitLab Free 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. -### Sum of issue weights **(STARTER)** +### Sum of issue weights **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, @@ -274,9 +271,6 @@ especially in combination with [assignee lists](#assignee-lists). ### Group issue boards **(PREMIUM)** -> - One group issue board per group introduced in GitLab 10.6. -> - Multiple group issue boards [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. - Accessible at the group navigation level, a group issue board offers the same features as a project-level board. It can display issues from all projects in that group and its descendant subgroups. Similarly, you can only filter by group labels for these @@ -360,9 +354,10 @@ You can also [drag issues](#drag-issues-between-lists) to change their position  -## Work In Progress limits **(STARTER)** +## Work In Progress limits **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 +> - Moved to GitLab Premium in 13.9. You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. @@ -435,13 +430,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 +456,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) @@ -547,8 +542,8 @@ to another list, the label changes and a system note is recorded. When dragging issues between lists, different behavior occurs depending on the source list and the target list. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -|----------------------------|--------------------|--------------|------------------------------|---------------------------------------| +| | To Open | To Closed | To label `B` list | To assignee `Bob` list | +| ------------------------------ | ------------------ | ------------ | ---------------------------- | ------------------------------------- | | **From Open** | - | Issue closed | `B` added | `Bob` assigned | | **From Closed** | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | | **From label `A` list** | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | @@ -563,7 +558,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.  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/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index d4fbc4fb10b..e1918b68ddc 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -99,9 +99,9 @@ confidential information prematurely. To make a confidential commit public, open a merge request from the private fork to the public upstream project. Permissions are inherited from parent groups. Developers have the same permissions -for private forks created in the same group or in a sub-group of the original +for private forks created in the same group or in a subgroup of the original Permissions are inherited from parent groups. When private forks are created -in the same group or sub-group as the original upstream repository, users +in the same group or subgroup as the original upstream repository, users receive the same permissions in both projects. This inheritance ensures Developer users have the needed permissions to both view confidential issues and resolve them. 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..5c95665230a 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -6,8 +6,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 12.10. Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. @@ -20,7 +19,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 @@ -49,10 +48,6 @@ Exported issues are always sorted by `Issue ID`. ## Format -> **Time Estimate** and **Time Spent** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2627) in GitLab Starter 10.0. -> -> **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. - Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 0d10f028cbf..2757642e458 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. Issues can be imported to a project by uploading a CSV file with the columns -`title` and `description`. +`title` and `description`. Other columns are **not** imported. If you want to +retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#moving-issues). The user uploading the CSV file is set as the author of the imported issues. 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..b6dff0842d8 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. @@ -259,4 +259,4 @@ This will be rendered as: User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), -and [project](../index.md#project-activity) activity pages. +and [project](../working_with_projects.md#project-activity) activity pages. 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  -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 - +> - [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..c3adce33826 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -23,13 +23,13 @@ The numbers in the image correspond to the following features: - **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) -- **4.** [Epic **(PREMIUM)**](#epic) + - **3.1.** [Multiple Assignees](#multiple-assignees) +- **4.** [Epic](#epic) - **5.** [Milestone](#milestone) - **6.** [Time tracking](#time-tracking) - **7.** [Due date](#due-date) - **8.** [Labels](#labels) -- **9.** [Weight **(STARTER)**](#weight) +- **9.** [Weight](#weight) - **10.** [Confidentiality](#confidentiality) - **11.** [Lock issue](#lock-issue) - **12.** [Participants](#participants) @@ -86,7 +86,7 @@ An issue can be assigned to: - Yourself. - Another person. -- [Many people](#multiple-assignees). **(STARTER)** +- [Many people](#multiple-assignees). **(PREMIUM)** The assignees can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. @@ -96,7 +96,7 @@ NOTE: If a user is not member of that project, it can only be assigned to them if they created the issue themselves. -#### Multiple Assignees **(STARTER)** +#### Multiple Assignees **(PREMIUM)** Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. @@ -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 @@ -138,7 +138,7 @@ available to all projects in the group. If a label doesn't exist yet, you can create one by clicking **Edit** followed by **Create new label** in the dropdown menu. -### Weight **(STARTER)** +### Weight **(PREMIUM)** [Assign a weight](issue_weight.md) to an issue. Larger values are used to indicate more effort is required to complete the issue. Only @@ -161,14 +161,9 @@ or were mentioned in the description or threads. ### Notifications -Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) +Select the toggle to enable or disable [notifications](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics) for the issue. Notifications are automatically enabled after you participate in the issue in any way. -- **Enable**: If you are not a participant in the discussion on that issue, but - want to receive notifications on each update, subscribe to it. -- **Disable**: If you are receiving notifications for updates to that issue but no - longer want to receive them, unsubscribe from it. - ### Reference - A quick "copy" button for that issue's reference, which looks like @@ -194,13 +189,14 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history). **(STARTER)** +[In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an +issue's description are listed in the [issue history](#issue-history). **(PREMIUM)** ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or `@groupname`. All mentioned users are notified via to-do items and emails, -unless they have disabled all notifications in their profile settings. +unless they have disabled all [notifications](#notifications) in their user settings. This is controlled in the [notification settings](../../profile/notifications.md). Mentions for yourself (the current logged in user) are highlighted @@ -244,8 +240,8 @@ Also: - You can mention a user or a group present in your GitLab instance with `@username` or `@groupname` and they are notified via to-do items - and emails, unless they have [disabled all notifications](#notifications) - in their profile settings. + and emails, unless they have disabled all [notifications](#notifications) + in their user settings. - Mentions for yourself (the current logged-in user) are highlighted in a different color, which allows you to quickly see which comments involve you. @@ -291,7 +287,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/issue_weight.md b/doc/user/project/issues/issue_weight.md index 4e2c8bfd7f1..b10debf9888 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -5,15 +5,15 @@ 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 weight **(STARTER)** +# Issue weight **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. +> - Moved to GitLab Premium in 13.9. When you have a lot of issues, it can be hard to get an overview. By adding a weight to each issue, you can get a better idea of how much time, value or complexity a given issue has or costs. -You can set the weight of an issue during its creation, by simply changing the +You can set the weight of an issue during its creation, by changing the value in the dropdown menu. You can set it to a non-negative integer value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the upper bound is essentially limitless). diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ef860df054e..f1739726cf8 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) @@ -287,9 +287,9 @@ editing it and clicking on the delete button. ## Promote an issue to an epic **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab Ultimate 11.6. +> - Moved to GitLab Premium in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. You can promote an issue to an epic in the immediate parent group. @@ -302,9 +302,10 @@ Alternatively, you can use the `/promote` [quick action](../quick_actions.md#qui Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). -## Add an issue to an iteration **(STARTER)** +## Add an issue to an iteration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. +> - Moved to GitLab Premium in 13.9. To add an issue to an [iteration](../../group/iterations/index.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/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index bb9038062f7..189777d40e7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Multiple Assignees for Issues **(STARTER)** +# Multiple Assignees for Issues **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). +> - Moved to GitLab Premium in 13.9. In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who @@ -40,4 +40,4 @@ to assign the issue to.  -An assignee can be easily removed by deselecting them from the same dropdown menu. +To remove an assignee, deselect them from the same dropdown menu. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 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/labels.md b/doc/user/project/labels.md index 22dfd3a8719..c0a66343a88 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -59,21 +59,25 @@ and edit labels. > Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. -To view the project labels list, navigate to the project and click **Issues > Labels**. -The list includes all labels that are defined at the project level, as well as all -labels defined by its ancestor groups. -For each label, you can see the project or group path from where it was created. -You can filter the list by entering a search query at the top and clicking search (**{search}**). +To view a project's available labels, in the project, go to **Issues > Labels**. +Its list of labels includes both the labels defined at the project level, and +all labels defined by its ancestor groups. For each label, you can see the +project or group path from where it was created. You can filter the list by +entering a search query in the **Filter** field, and then clicking its search +icon (**{search}**). To create a new project label: -1. Navigate to **Issues > Labels** in the project. -1. Click the **New label** button. - - Enter the title. - - (Optional) Enter a description. - - (Optional) Select a background color by clicking on the available colors, or input - a hex color value for a specific color. -1. Click **Create label** to create the label. +1. In your project, go to **Issues > Labels**. +1. Select the **New label** button. +1. In the **Title** field, enter a short, descriptive name for the label. You + can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). +1. (Optional) In the **Description** field, you can enter additional + information about how and when to use this label. +1. (Optional) Select a background color for the label by selecting one of the + available colors, or by entering a hex color value in the **Background color** + field. +1. Select **Create label**. You can also create a new project label from within an issue or merge request. In the label section of the right sidebar of an issue or a merge request: 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. - + 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 - +> - [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. + + + +#### Display direct members + +To display direct members, include `Membership` `=` `Direct` in the search text box. + + + +### Search + +You can search for members by name, username, or email. + + + +### Sort + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. + + ## Add a user Right next to **People**, start typing the name or username of the user you want to add. - + 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. - + Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above. - + 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. - + 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. - + ## 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. - + As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project. - + 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. - + 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. - + 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**. -  +  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. -  +  - 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..7aa7673366d 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Allow collaboration on merge requests across forks +# Allow collaboration on merge requests across forks **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. @@ -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: @@ -78,8 +78,23 @@ Here's how the process would look like: local branch `thedude-awesome-project-update-docs` to the `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. -<!-- ## Troubleshooting +## Troubleshooting + +### Pipeline status unavailable from MR page of forked project + +When a user forks a project, the permissions on the forked copy are not copied over +from the original project. The creator of the fork must grant permissions to the +forked copy before members in the upstream project can view or merge the changes +in the merge request. +To see the pipeline status from the merge request page of a forked project +going back to the original project: + +1. Create a group containing all the upstream members. +1. Go to the **Members** tab in the forked project and invite the newly-created + group to the forked project. + +<!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's important to describe those, too. Think of things that may go wrong and include them here. diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 7bb64987a31..36481ac0133 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Authorization for Merge requests +# Authorization for Merge requests **(FREE)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4e87876b036..4c9a6557320 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Cherry-pick changes +# Cherry-pick changes **(FREE)** GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") @@ -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.  -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.  -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:  -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..55dc0bcc41a 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 @@ -73,9 +73,9 @@ GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). - 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. +- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality 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: @@ -161,6 +161,7 @@ to be consider, but may be preferable depending on your use case. --locked="false" \ --access-level="not_protected" \ --docker-volumes "/cache"\ + --docker-volumes "/builds:/builds"\ --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ --registration-token="<project_token>" \ --non-interactive @@ -173,8 +174,8 @@ to be consider, but may be preferable depending on your use case. in the previous step. ```shell - --builds-dir /tmp/builds - --docker-volumes /tmp/builds:/tmp/builds + --builds-dir "/tmp/builds" + --docker-volumes "/tmp/builds:/tmp/builds" # Use this instead of --docker-volumes "/builds:/builds" ``` The resulting configuration: @@ -219,8 +220,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:  @@ -358,7 +359,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 +412,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 @@ -421,6 +422,71 @@ for more details. Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_project) that uses Code Quality with a `.codeclimate.yml` file. +## Use a Code Quality image hosted in a registry with untrusted certificates + +If you set the `CODE_QUALITY_IMAGE` to an image that is hosted in a +Docker registry which uses a TLS certificate that is not trusted, such as +a self-signed certificate, you can see errors like the one below: + +```shell +$ docker pull --quiet "$CODE_QUALITY_IMAGE" +Error response from daemon: Get https://gitlab.example.com/v2/: x509: certificate signed by unknown authority +``` + +To fix this, configure the Docker daemon to [trust certificates](https://docs.docker.com/registry/insecure/#use-self-signed-certificates) +by putting the certificate inside of the `/etc/docker/certs.d` +directory. + +This Docker daemon is exposed to the subsequent Code Quality Docker container in the +[GitLab Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml#L41) +and should be to exposed any other containers in which you want to have +your certificate configuration apply. + +### Docker + +If you have access to GitLab Runner configuration, add the directory as a +[volume mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). For example: + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + volumes = ["/cache", "/etc/gitlab-runner/certs/gitlab.example.com.crt:/etc/docker/certs.d/gitlab.example.com/ca.crt:ro"] +``` + +Replace `gitlab.example.com` with the actual domain of the registry. + +### Kubernetes + +If you have access to GitLab Runner configuration and the Kubernetes cluster, +you can [mount a ConfigMap](https://docs.gitlab.com/runner/executors/kubernetes.html#configmap-volumes): + +1. Create a ConfigMap with the certificate: + + ```shell + kubectl create configmap registry-crt --namespace gitlab-runner --from-file /etc/gitlab-runner/certs/gitlab.example.com.crt + ``` + +1. Update GitLab Runner `config.toml` to specify the ConfigMap: + + ```toml + [[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "registry-crt" + mount_path = "/etc/docker/certs.d/gitlab.example.com/ca.crt" + sub_path = "gitlab.example.com.crt" + ``` + +Replace `gitlab.example.com` with the actual domain of the registry. + ## Troubleshooting ### Changing the default configuration has no effect @@ -428,7 +494,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 @@ -438,21 +504,51 @@ This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to compare to yet, so no information can be displayed. It only displays after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports will not have anything to compare to. +- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD 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`. + +### Rubocop errors + +When using Code Quality jobs on a Ruby project, you can encounter problems running Rubocop. +For example, the following error can appear when using either a very recent or very old version +of Ruby: + +```plaintext +/usr/local/bundle/gems/rubocop-0.52.1/lib/rubocop/config.rb:510:in `check_target_ruby': +Unknown Ruby version 2.7 found in `.ruby-version`. (RuboCop::ValidationError) +Supported versions: 2.1, 2.2, 2.3, 2.4, 2.5 +``` + +This is caused by the default version of Rubocop used by the check engine not covering +support for the Ruby version in use. + +To use a custom version of Rubocop that +[supports the version of Ruby used by the project](https://docs.rubocop.org/rubocop/compatibility.html#support-matrix), +you can [override the configuration through a `.codeclimate.yml` file](https://docs.codeclimate.com/docs/rubocop#using-rubocops-newer-versions) +created in the project repository. + +For example, to specify using Rubocop release **0.67**: + +```yaml +version: "2" +plugins: + rubocop: + enabled: true + channel: rubocop-0-67 +``` 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..5cfedc6c9f1 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,7 +7,7 @@ description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# How to create a merge request +# How to create a merge request **(FREE)** Before creating a merge request, read through an [introduction to Merge Requests](getting_started.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/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index a89acff4bfc..c4a34f9c65c 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Fast-forward merge requests +# Fast-forward merge requests **(FREE)** Sometimes, a workflow policy might mandate a clean commit history without merge commits. In such cases, the fast-forward merge is the perfect candidate. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index dc5e1f81a63..b1a57d9c3e6 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -6,7 +6,7 @@ type: index, reference description: "Getting started with Merge Requests." --- -# Getting started with Merge Requests +# Getting started with Merge Requests **(FREE)** A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version control. @@ -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 @@ -114,16 +115,9 @@ It is also possible to manage multiple assignees: ### Reviewer > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - 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/49787) on GitLab 13.7. -> - 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. WARNING: -This feature might not be available to you. Check the **version history** note above for details. - Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. @@ -136,48 +130,14 @@ 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)** - -Merge Request Reviewers 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 -# For the instance -Feature.enable(:merge_request_reviewers) -# For a single project -Feature.enable(:merge_request_reviewers, Project.find(<project id>)) -``` - -To disable it: +#### Approval Rule information for Reviewers **(PREMIUM)** -```ruby -# For the instance -Feature.disable(:merge_request_reviewers) -# For a single project -Feature.disable(:merge_request_reviewers, Project.find(<project id>)) -``` - -#### Approval Rule information for Reviewers **(STARTER)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - 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)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. For this version only, GitLab administrators can opt to [enable it](#enable-or-disable-approval-rule-information). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](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,30 +147,20 @@ This example shows reviewers and approval rules in a merge request sidebar:  -##### Enable or disable Approval Rule information for Reviewers **(STARTER ONLY)** +#### Requesting a new review -Merge Request Reviewers is under development and 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: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. -```ruby -# For the instance -Feature.enable(:reviewer_approval_rules) -# For a single project -Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) -``` +After a reviewer completes their [merge request reviews](../../discussions/index.md), +the author of the merge request can request a new review from the reviewer: -To disable it: +1. If the right sidebar in the merge request is collapsed, click the + **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. +1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) + next to the reviewer's name. -```ruby -# For the instance -Feature.disable(:reviewer_approval_rules) -# For a single project -Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) -``` +GitLab creates a new [to-do item](../../todos.md) for the reviewer, and sends +them a notification email. ### Merge requests to close issues @@ -244,6 +194,33 @@ is set for deletion, the merge request widget displays the  +### Branch retargeting on merge **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - 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-branch-retargeting-on-merge). + +In specific circumstances, GitLab can retarget the destination branch of +open merge request, if the destination branch merges while the merge request is +open. Merge requests are often chained in this manner, with one merge request +depending on another: + +- **Merge request 1**: merge `feature-alpha` into `master`. +- **Merge request 2**: merge `feature-beta` into `feature-alpha`. + +These merge requests are usually handled in one of these ways: + +- Merge request 1 is merged into `master` first. Merge request 2 is then + retargeted to `master`. +- Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which + now contains the contents of `feature-alpha` and `feature-beta`, is merged into `master`. + +GitLab retargets up to four merge requests when their target branch is merged into +`master`, so you don't need to perform this operation manually. Merge requests from +forks are not retargeted. + ## Recommendations and best practices for Merge Requests - When working locally in your branch, add multiple commits and only push when @@ -253,3 +230,49 @@ is set for deletion, the merge request widget displays the - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. + +## Enable or disable Approval Rule information **(PREMIUM SELF)** + +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. + +Merge Request Reviewers is under development and 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 +# For the instance +Feature.enable(:reviewer_approval_rules) +# For a single project +Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:reviewer_approval_rules) +# For a single project +Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +### Enable or disable branch retargeting on merge **(FREE SELF)** + +Automatically retargeting merge requests is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:retarget_merge_requests) +``` + +To disable it: + +```ruby +Feature.disable(:retarget_merge_requests) +``` diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 6af6cad5cdd..8ccf50e48b8 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge requests +# Merge requests **(FREE)** A Merge Request (**MR**) is a _request_ to _merge_ one branch into another. 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..1fcc09a9d8a 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,16 +119,17 @@ To enable this merge request approval rule:  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. Alternatively, you can **require** -[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** +[Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** #### 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,20 +214,20 @@ 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.  -#### Scoped to Protected Branch **(PREMIUM)** +#### Scoped to protected branch **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. @@ -236,7 +239,7 @@ the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - + To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). @@ -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,24 +319,38 @@ 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 +You can prevent authors from approving their own merge requests +[at the instance level](../../admin_area/merge_requests_approvals.md). When enabled, +this setting is disabled on the project level, and not editable. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +#### Prevent approval of merge requests by their committers **(PREMIUM)** -You can prevent users that have committed to a merge request from approving it. To -enable this feature: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +You can prevent users who have committed to a merge request from approving it, +though code authors can still approve. You can enable this feature +[at the instance level](../../admin_area/merge_requests_approvals.md), which +disables changes to this feature at the project level. If you prefer to manage +this feature at the project level, you can: 1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. + If this check box is disabled, this feature has been disabled + [at the instance level](../../admin_area/merge_requests_approvals.md). 1. Click **Save changes**. +Read the official Git documentation for an explanation of the +[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). + #### 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..d33a8e40aac 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge when pipeline succeeds +# Merge when pipeline succeeds **(FREE)** When reviewing a merge request that looks ready to merge but still has a pipeline running, you can set it to merge automatically when the @@ -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..a53b5032e1d 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -5,18 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request conflict resolution +# Merge request conflict resolution **(FREE)** 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:  -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**.  @@ -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/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 40a4631694b..d5d0578c07c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Reverting changes +# Reverting changes **(FREE)** You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") by clicking the **Revert** button in merge requests and commit details. 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..94f48fa544f 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).  @@ -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,21 +80,23 @@ 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, select your avatar. +1. Select **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Select **Save changes**. + +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.  -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: 1. Go to the merge request's **Changes** tab. -1. Click the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. 1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. This change overrides the choice you made in your user preferences and persists until you clear your @@ -104,10 +106,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. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons on the top-right of the page. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  @@ -120,7 +126,7 @@ to expand the entire file.  -[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,24 +142,60 @@ 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.  ### Commenting on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221268) on GitLab 13.3. -> - 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. 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,53 +211,33 @@ above it.  -### Enable or disable multiline comments **(CORE ONLY)** - -The multiline comments feature is under development but 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 opt to enable it for your instance. - -To disable it: - -```ruby -Feature.disable(:multiline_comments) -``` - -To enable it: - -```ruby -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.  @@ -223,14 +245,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 +263,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 +292,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 +308,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 +319,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 +328,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 +337,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 +359,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..1b99b1b5c44 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Squash and merge +# Squash and merge **(FREE)** > - [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/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 3960f916f9b..e60f2f712d3 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -52,7 +52,52 @@ Hovering over the coverage bar will provide further information, such as the num of times the line was checked by tests. NOTE: -The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that +A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds +100 nodes, there can be mismatches or no matches in the Merge Request diff view. + +### Automatic class path correction + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284822) in GitLab 13.9. + +For the coverage report to properly match the files displayed on a merge request diff, the `filename` of a `class` element +must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated +Cobertura XML has the `filename` path relative to the class package directory instead. + +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser will attempt to build the +full path by doing following: + +1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. +1. Check if the candidate path exists in the project. +1. Use the first candidate that matches as the class full path. + +As an example scenario, given the project's full path is `test-org/test-project`, and has the following file tree relative +to the project root: + +```shell +Auth/User.cs +Lib/Utils/User.cs +``` + +And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: + +```xml +<sources> + <source>/builds/test-org/test-project/Auth</source> + <source>/builds/test-org/test-project/Lib/Utils</source> +</sources> +``` + +The parser will extract `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to +the project root, combining these extracted sources and the class filename. + +If for example there is a `class` element with the `filename` value of `User.cs`, the parser will take the first candidate path +that matches which is `Auth/User.cs`. + +For each `class` element, the parser will attempt to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. + +NOTE: +The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser will assume that the `filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 4ad960413ef..8f3ce9186f1 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,9 +64,10 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In the future it will -[replace](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the -current default comparison. +by selecting **master (HEAD)**. In GitLab 13.9, it +[replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the +old default comparison. For technical details, additional information is available in the +[developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch).  diff --git a/doc/user/project/merge_requests/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.  @@ -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.  diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 3e266d054be..7c22b271ec2 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -5,18 +5,17 @@ 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 --- -# Burndown and burnup charts **(STARTER)** +# Burndown and burnup charts **(PREMIUM)** [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone.  -## Burndown charts +## Burndown charts **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. +> - Moved to GitLab Premium in 13.9. Burndown charts show the number of issues over the course of a milestone. @@ -101,10 +100,11 @@ Therefore, when the milestone start date is changed, the number of opened issues change. Reopened issues are considered as having been opened on the day after they were last closed. -## Burnup charts +## Burnup charts **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in GitLab 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in GitLab 13.7. +> - Moved to GitLab Premium in 13.9. Burnup charts show the assigned and completed work for a milestone. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index acf32bb0f92..fe34dca4959 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. @@ -123,10 +123,16 @@ From the project and group issue/merge request list pages, you can [filter](../. ### Filtering in issue boards -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). -- From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** -- From [group issue boards](../issue_board.md#group-issue-boards) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** +From [project issue boards](../issue_board.md), you can filter by both group milestones and project +milestones in: + +- [Search and filter bar](../../search/index.md#issue-boards) +- [Issue board configuration](../issue_board.md#configurable-issue-boards) + +From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in: + +- [Search and filter bar](../../search/index.md#issue-boards) +- [Issue board configuration](../issue_board.md#configurable-issue-boards) ### Special milestone filters @@ -155,15 +161,17 @@ There are also tabs below these that show the following: - **Participants**: Shows all assignees of issues assigned to the milestone. - **Labels**: Shows all labels that are used in issues assigned to the milestone. -### Project Burndown Charts **(STARTER)** +### Project Burndown Charts -For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. +For project milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +showing the progress of completing a milestone.  -### Group Burndown Charts **(STARTER)** +### Group Burndown Charts -For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. +For group milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 4910751ece1..585d97c74c2 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -195,7 +195,7 @@ As a user: ### Dependent repositories -The [Job environment variable](../../ci/variables/README.md#predefined-environment-variables) `CI_JOB_TOKEN` can be used to +The [CI/CD variable](../../ci/variables/README.md#predefined-cicd-variables) `CI_JOB_TOKEN` can be used to authenticate any clones of dependent repositories. For example: ```shell 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..d9ec2aae2b7 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 @@ -18,7 +18,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). +1. Click the name of the project you want to [fork](../../../../user/project/working_with_projects.md#fork-a-project). 1. In the top right, click the **Fork** button, and then choose a namespace to fork to. 1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. GitLab CI/CD builds and deploys your site. @@ -52,5 +52,5 @@ You can take some **optional** further steps:  - - 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..4629c87f41e 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Protected branches +# Protected branches **(FREE)** [Permissions](../permissions.md) in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -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,66 +21,69 @@ 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.  -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.  ## 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.  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 +### Allow deploy keys to push to a protected branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. > - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users. +> - This feature is available for all users in GitLab 13.9. You can allow specific machines to access protected branches in your repository with -[Deploy Keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, +[deploy keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, for example. Deploy keys can be selected in the **Allowed to push** dropdown when: @@ -88,7 +91,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. @@ -97,30 +100,26 @@ For a deploy key to be selectable: - It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). - It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. -Deploy Keys are not available in the **Allowed to merge** dropdown. - - +Deploy keys are not available in the **Allowed to merge** dropdown. -## 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.  -Click **Protect** and the branch will appear in the "Protected branch" list. +Click **Protect** and the branch displays in the **Protected branch** list.  ## 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 +128,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:  @@ -151,41 +150,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.  -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)** +## 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 +202,7 @@ To enable Code Owner's approval to branches already protected:  -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 +218,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..3ea0bb62c0b 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Protected tags +# Protected tags **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. @@ -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.  -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**:  -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:  ## 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:  diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 8af4307c013..f94a4075363 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Push Options +# Push Options **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) in GitLab 11.7. 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..b5751797870 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. @@ -475,6 +475,16 @@ terminal. Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. +## Release Metrics **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. + +Group-level release metrics are available by navigating to **Group > Analytics > CI/CD**. +These metrics include: + +- Total number of releases in the group +- Percentage of projects in the group that have at least one release + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index ffd4b383bcb..4d0cf28593d 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Branches +# Branches **(FREE)** A branch is a version of a project's working tree. You create a branch for each set of related changes you make. This keeps each set of changes separate from @@ -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.  -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/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index f7da3629c23..1a5e169ec6b 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- -# Project forking workflow +# Project forking workflow **(FREE)** Whenever possible, it's recommended to work in a common Git repository and use [branching strategies](../../../topics/gitlab_flow.md) to manage your work. However, diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 4322c79daa7..81995291911 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file blame." --- -# Git file blame +# Git file blame **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 51cc6bb3483..2e27cab4177 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file history." --- -# Git file history +# Git file history **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/blob/9ba1224867665844b117fa037e1465bb706b3685/app/controllers/commits_controller.rb) in GitLab 0.8.0 diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 57e9d814c95..1a46c140507 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits with GPG +# Signing commits with GPG **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9546) in GitLab 9.5. > - Subkeys support was added in GitLab 10.1. @@ -138,27 +138,25 @@ started: gpg --armor --export 30F2B65B9246B6CA ``` -1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account) +1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account) ## Adding a GPG key to your account NOTE: -Once you add a key, you cannot edit it, only remove it. In case the paste -didn't work, you'll have to remove the offending key and re-add it. +After you add a key, you cannot edit it, only remove it. In case the paste +didn't work, you have to remove the offending key and re-add it. -You can add a GPG key in your profile's settings: +You can add a GPG key in your user settings: -1. On the upper right corner, click on your avatar and go to your **Settings**. - -  - -1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key' - box. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Paste your _public_ key in the **Key** text box.  -1. Finally, click on **Add key** to add it to GitLab. You will be able to see - its fingerprint, the corresponding email address and creation date. +1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding + email address, and creation date.  @@ -248,22 +246,24 @@ in case your key has been compromised. To revoke a GPG key: -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **GPG keys** tab. -1. Click on **Revoke** besides the GPG key you want to delete. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Select **Revoke** next to the GPG key you want to delete. ## Removing a GPG key Removing a key **does not unverify** already signed commits. Commits that were -verified by using this key will stay verified. Only unpushed commits will stay -unverified once you remove this key. To unverify already signed commits, you need +verified by using this key stay verified. Only unpushed commits stay +unverified after you remove this key. To unverify already signed commits, you need to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. To remove a GPG key from your account: -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **GPG keys** tab. -1. Click on the trash icon besides the GPG key you want to delete. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. ## Rejecting commits that are not signed **(PREMIUM)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index c4f5d330f63..5a915ebef89 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Repository +# Repository **(FREE)** A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) is what you use to store your codebase in GitLab and change it with version control. @@ -14,7 +14,7 @@ A repository is part of a [project](../index.md), which has a lot of other featu ## Create a repository To create a new repository, all you need to do is -[create a new project](../../../gitlab-basics/create-project.md) or +[create a new project](../../../user/project/working_with_projects.md#create-a-project) or [fork an existing project](forking_workflow.md). Once you create a new project, you can add new files via UI @@ -43,7 +43,7 @@ You can either use the user interface (UI), or connect your local computer with GitLab [through the command line](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy -your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/README.md) +your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/index.md) to your repository's root. **From the user interface:** @@ -242,13 +242,32 @@ Learn how to [clone a repository through the command line](../../../gitlab-basic Alternatively, clone directly into a code editor as documented below. -### Clone to Apple Xcode +### Clone and open in Apple Xcode > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned -into Xcode using the new **Open in Xcode** button, located next to the Git URL -used for cloning your project. The button is only shown on macOS. +into Xcode on macOS. To do that: + +1. From the GitLab UI, go to the project's overview page. +1. Click **Clone**. +1. Select **Xcode**. + +The project will be cloned onto your computer in a folder of your choice and you'll +be prompted to open in XCode. + +### Clone and open in Visual Studio Code + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.8. + +All projects can be cloned into Visual Studio Code. To do that: + +1. From the GitLab UI, go to the project's overview page. +1. Click **Clone**. +1. Select **VS Code** + +You'll be prompted to select a folder to clone the project into. When VS Code has +successfully cloned your project, it will open the folder. ## Download Source Code @@ -270,6 +289,28 @@ By clicking the download icon, a dropdown will open with links to download the f - **Artifacts:** allows users to download the artifacts of the latest CI build. +## Redirects when changing repository paths + +When a repository path changes, it is essential to smoothly transition from the +old location to the new one. GitLab provides two kinds of redirects: the web UI +and Git push/pull redirects. + +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 (such as projects) will + redirect to the new URLs. +- Starting with GitLab 10.3, existing Git remote URLs for projects under the + namespace redirect to the new remote URL. Every time you push/pull to a + repository that has changed its location, a warning message to update + your remote is displayed instead of rejecting your action. + This means that any automation scripts, or Git clients continue to + work after a rename, making any transition a lot smoother. +- The redirects are available as long as the original path is not claimed by + another group, user or project. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 91fe9049b53..123df9097f9 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -4,7 +4,7 @@ group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- -# Jupyter Notebook Files +# Jupyter Notebook Files **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. 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..4d5e4a5ef02 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- -# Repository mirroring +# Repository mirroring **(FREE)** Repository mirroring allows for mirroring of repositories to and from external sources. It can be used to mirror branches, tags, and commits between repositories. It is useful when you want to use @@ -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: @@ -332,7 +340,7 @@ If you're mirroring over SSH (that is, using an `ssh://` URL), you can authentic - Password-based authentication, just as over HTTPS. - Public key authentication. This is often more secure than password authentication, - especially when the other repository supports [Deploy Keys](../../../ssh/README.md#deploy-keys). + especially when the other repository supports [deploy keys](../../../ssh/README.md#deploy-keys). To get started: @@ -393,7 +401,7 @@ GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SS You then need to add the public SSH key to the other repository's configuration: - If the other repository is hosted on GitLab, you should add the public SSH key - as a [Deploy Key](../../../ssh/README.md#deploy-keys). + as a [deploy key](../../../ssh/README.md#deploy-keys). - If the other repository is hosted elsewhere, you may need to add the key to your user's `authorized_keys` file. Paste the entire public SSH key into the file on its own line and save it. @@ -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.  -## 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:  -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:  -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.  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:  -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.  @@ -120,46 +122,47 @@ This dropdown contains the options **Create merge request and branch** and **Cre  -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. - +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. +  - +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. + +  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. - +  -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. - +  ## 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. - +  -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/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 639bca0d354..29c1c32145d 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits and tags with X.509 +# Signing commits and tags with X.509 **(FREE)** [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c99b0d91523..c7dda81685c 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -23,6 +23,10 @@ When a feature is no longer necessary, you can [archive the related requirement] <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a more in-depth walkthrough using a [demonstration project](https://gitlab.com/gitlab-org/requiremeents-mgmt), +see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) (Feb 2021). +  ## Create a requirement @@ -260,7 +264,9 @@ 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. +> - Ability to select which fields to export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290823) 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 @@ -275,19 +281,41 @@ Users with Reporter or higher [permissions](../../permissions.md) can export req To export requirements: 1. In a project, go to **Requirements**. -1. Select the **Export as CSV** icon (**{export}**) in the top right. A confirmation modal appears. +1. In the top right, select the **Export as CSV** icon (**{export}**). + + A confirmation modal appears. + +1. Under **Advanced export options**, select which fields to export. + + All fields are selected by default. To exclude a field from being exported, clear the checkbox next to it. + 1. Select **Export requirements**. The exported CSV file is sent to the email address associated with your user. ### 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 headers: + +- In GitLab 13.8: + + - Requirement ID + - Title + - Description + - Author Username + - Latest Test Report State + - Latest Test Report Created At (UTC) -The exported CSV file contains the following columns: +- In GitLab 13.9 and later: -- Requirement ID -- Title -- Description -- Author Username -- Latest Test Report State -- Latest Test Report Created At (UTC) + - 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..debe5c51d51 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -4,11 +4,9 @@ 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 to GitLab Free 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 +32,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. @@ -56,74 +54,99 @@ Here's how Service Desk works for you: ## Configuring Service Desk -NOTE: -Service Desk is enabled on GitLab.com. -You can skip step 1 below; you only need to enable it per project. +Users with Maintainer and higher access in a project can configure Service Desk. + +Service Desk issues are [confidential](issues/confidential_issues.md), so they are +only visible to project members. In GitLab 11.7 we updated the generated email +address format. The older format is still supported, so existing aliases or +contacts still work. + +If you have [templates](description_templates.md) in your repository, you can optionally select +one from the selector menu to append it to all Service Desk issues. -If you have project maintainer access you have the option to set up Service Desk. Follow these steps: +To enable Service Desk in your project: -1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. +1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), - but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). -1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. + but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). +1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. These issues are [confidential](issues/confidential_issues.md), so they are - only visible to project members. Note that in GitLab 11.7, we updated the generated email - address's format. The older format is still supported, however, allowing existing aliases or - contacts to continue working. + to the project. - WARNING: - This email address can be used by anyone to create an issue on this project, regardless - of their access level to your GitLab instance. We recommend **putting this behind an alias** so it can be - changed if needed. We also recommend **[enabling Akismet](../../integration/akismet.md)** on your GitLab - instance to add spam checking to this service. Unblocked email spam would result in many spam - issues being created. +Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select +**Issues > Service Desk**. - If you have [templates](description_templates.md) in your repository, you can optionally select - one from the selector menu to append it to all Service Desk issues. +WARNING: +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their access level** to your GitLab instance. -Service Desk is now enabled for this project! You should be able to access it from your project's -**Issues** menu. +To improve your project's security, we recommend the following: - +- Put the Service Desk email address behind an alias on your email system so you can change it later. +- [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. + Unblocked email spam can result in many spam issues being created. + +The unique internal email address is visible to project members with Maintainer (or higher) +[permission level](../permissions.md) +in your GitLab instance. However, when using an email alias externally, an end user +(issue creator) cannot see the internal email address displayed in the information note. ### Using customized email templates -> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab Premium 12.7. +> - Moved to GitLab Free 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. @@ -139,7 +162,7 @@ To edit the custom email display name: ### Using custom email address -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. If the `service_desk_email` is configured, then you can create Service Desk @@ -215,7 +238,8 @@ The configuration options are the same as for configuring ## Using Service Desk -There are a few ways Service Desk can be used. +You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). +In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). ### As an end user (issue creator) 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..8ab82fe7296 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, index, howto --- -# Project settings +# Project settings **(FREE)** NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) @@ -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)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +GitLab 13.9 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 subgroups. 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, project and group owners +can now create their 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, @@ -59,7 +79,7 @@ Use the switches to enable or disable the following features: | **Issues** | ✓ | Activates the GitLab issues tracker | | **Repository** | ✓ | Enables [repository](../repository/) functionality | | **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | +| **Forks** | ✓ | Enables [forking](../working_with_projects.md#fork-a-project) functionality | | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | @@ -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:  -### Service Desk **(STARTER)** +### Service Desk Enable [Service Desk](../service_desk.md) for your project to offer customer support. @@ -201,7 +221,7 @@ To rename a repository: Remember that this can have unintended side effects since everyone with the old URL won't be able to push or pull. Read more about what happens with the -[redirects when renaming repositories](../index.md#redirects-when-changing-repository-paths). +[redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths). #### Transferring an existing project into another namespace @@ -225,7 +245,7 @@ To transfer a project: Once done, you will be taken to the new project's namespace. At this point, read what happens with the -[redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths). +[redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). NOTE: GitLab administrators can use the administration interface to move any project to any @@ -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)** + +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..002eb398406 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,11 +68,11 @@ 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) - or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates). + or [create a new project from a template](../working_with_projects.md#built-in-templates). 1. Edit the [`data/config.yml`](#static-site-generator-configuration) configuration file to replace `<username>` and `<project-name>` with the proper values for your project's path. @@ -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..07f46cb94f7 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,12 +5,12 @@ 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 +The Web Integrated Development Environment (IDE) editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. ## Open the Web IDE @@ -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..187fcb5b3f9 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 @@ -184,7 +184,7 @@ Similar to versioned diff file views, you can see the changes made in a given Wi Wiki events (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), -and [project](../index.md#project-activity) activity pages. +and [project](../working_with_projects.md#project-activity) activity pages. ## Adding and editing wiki pages locally diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md new file mode 100644 index 00000000000..3fe6193c414 --- /dev/null +++ b/doc/user/project/working_with_projects.md @@ -0,0 +1,341 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +--- + +# Working with projects **(FREE)** + +Most work in GitLab is done in a [project](../../user/project/index.md). Files and +code are saved in projects, and most features are in the scope of projects. + +## Explore projects + +You can explore other popular projects available on GitLab. To explore projects: + +1. Click **Projects** in the navigation bar. +1. Click **Explore Projects**. + +GitLab displays a list of projects, sorted by last updated date. To view +projects with the most [stars](#star-a-project), click **Most stars**. To view +projects with the largest number of comments in the past month, click **Trending**. + +## Create a project + +To create a project in GitLab: + +1. In your dashboard, click the green **New project** button or use the plus + icon in the navigation bar. This opens the **New project** page. +1. On the **New project** page, choose if you want to: + - Create a [blank project](#blank-projects). + - Create a project using one of the available [project templates](#project-templates). + - [Import a project](../../user/project/import/index.md) from a different repository, + if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. + - Run [CI/CD pipelines for external repositories](../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** + +NOTE: +For a list of words that can't be used as project names see +[Reserved project and group names](../../user/reserved_names.md). + +### Blank projects + +To create a new blank project on the **New project** page: + +1. On the **Blank project** tab, provide the following information: + - The name of your project in the **Project name** field. You can't use + special characters, but you can use spaces, hyphens, underscores, or even + emoji. When adding the name, the **Project slug** auto populates. + The slug is what the GitLab instance uses as the URL path to the project. + If you want a different slug, input the project name first, + then change the slug after. + - The path to your project in the **Project slug** field. This is the URL + path for your project that the GitLab instance uses. If the + **Project name** is blank, it auto populates when you fill in + the **Project slug**. + - The **Project description (optional)** field enables you to enter a + description for your project's dashboard, which helps others + understand what your project is about. Though it's not required, it's a good + idea to fill this in. + - Changing the **Visibility Level** modifies the project's + [viewing and access rights](../../public_access/public_access.md) for users. + - Selecting the **Initialize repository with a README** option creates a + README file so that the Git repository is initialized, has a default branch, and + can be cloned. +1. Click **Create project**. + +### Project templates + +Project templates can pre-populate a new project with the necessary files to get you +started quickly. + +There are two main types of project templates: + +- [Built-in templates](#built-in-templates), sourced from the following groups: + - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) + - [`pages`](https://gitlab.com/pages) +- [Custom project templates](#custom-project-templates), for custom templates + configured by GitLab administrators and users. + +#### Built-in templates + +Built-in templates are project templates that are: + +- Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) + and [`pages`](https://gitlab.com/pages) groups. +- Released with GitLab. + +To use a built-in template on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is + the same as creating a [blank project](#blank-projects). + +##### Enterprise templates **(ULTIMATE)** + +GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. + +To create a new project with an Enterprise template, on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in Enterprise templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is the same as creating a [blank project](#blank-projects). + +Available Enterprise templates include: + +- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) + +NOTE: +You can improve the existing built-in templates or contribute new ones in the +[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and +[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). + +##### Custom project templates **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. + +Creating new projects based on custom project templates is a convenient option for +quickly starting projects. + +Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) +from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) +from the **Group** tab, under the **Create from template** tab. + +To use a custom project template on the **New project** page: + +1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. +1. From the list of available custom templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is + the same as creating a [blank project](#blank-projects). + +## Push to create a new project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + +When you create a new repository locally, instead of manually creating a new project in GitLab +and then [cloning the repository](../../gitlab-basics/start-using-git.md#clone-a-repository) +locally, you can directly push it to GitLab to create the new project, all without leaving +your terminal. If you have access rights to the associated namespace, GitLab +automatically creates a new project under that GitLab namespace with its visibility +set to Private by default (you can later change it in the [project's settings](../../public_access/public_access.md#how-to-change-project-visibility)). + +This can be done by using either SSH or HTTPS: + +```shell +## Git push using SSH +git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master + +## Git push using HTTPS +git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master +``` + +You can pass the flag `--tags` to the `git push` command to export existing repository tags. + +Once the push finishes successfully, a remote message indicates +the command to set the remote and the URL to the new project: + +```plaintext +remote: +remote: The private project namespace/nonexistent-project was created. +remote: +remote: To configure the remote, run: +remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git +remote: +remote: To view the project, visit: +remote: https://gitlab.example.com/namespace/nonexistent-project +remote: +``` + +## Fork a project + +A fork is a copy of an original repository that you put in another namespace +where you can experiment and apply changes that you can later decide whether or +not to share, without affecting the original project. + +It takes just a few steps to [fork a project in GitLab](repository/forking_workflow.md#creating-a-fork). + +## Star a project + +You can star a project to make it easier to find projects you frequently use. +The number of stars a project has can indicate its popularity. + +To star a project: + +1. Go to the home page of the project you want to star. +1. In the upper right corner of the page, click **Star**. + +To view your starred projects: + +1. Click **Projects** in the navigation bar. +1. Click **Starred Projects**. +1. GitLab displays information about your starred projects, including: + + - Project description, including name, description, and icon + - Number of times this project has been starred + - Number of times this project has been forked + - Number of open merge requests + - Number of open issues + +## Delete a project + +To delete a project, first navigate to the home page for that project. + +1. Navigate to **Settings > General**. +1. Expand the **Advanced** section. +1. Scroll down to the **Delete project** section. +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 in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). + +## Project settings + +Set the project's visibility level and the access levels to its various pages +and perform actions like archiving, renaming or transferring a project. + +Read through the documentation on [project settings](settings/index.md). + +## Project activity + +To view the activity of a project, navigate to **Project overview > Activity**. +From there, you can click on the tabs to see **All** the activity, or see it +filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, +**Team**, and **Wiki**. + +### Leave a project + +**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 are no longer a project +member, and cannot contribute. + +## Use your project as a Go package + +Any project can be used as a Go package. GitLab responds correctly to `go get` +and `godoc.org` discovery requests, including the +[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and +[`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 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 truncates the path for +private projects in subgroups to the first two segments, causing `go get` to +fail. + +GitLab implements its own Go proxy. This feature must be enabled by an +administrator and requires additional configuration. See [GitLab Go +Proxy](../packages/go_proxy/index.md). + +### Disable Go module features for private projects + +In Go 1.12 and later, Go queries module proxies and checksum databases in the +process of [fetching a +module](../../development/go_guide/dependencies.md#fetching). This can be +selectively disabled with `GOPRIVATE` (disable both), +[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy +queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) +(disable checksum queries). + +`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go +modules and Go module prefixes. For example, +`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`. + +### Authenticate Go requests + +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 +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: + +```plaintext +machine gitlab.example.com +login <gitlab_user_name> +password <personal_access_token> +``` + +NOTE: +On Windows, Go reads `~/_netrc` instead of `~/.netrc`. + +### Authenticate Git fetches + +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: +git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + +# Use SSH instead of HTTPS: +git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" +``` + +## Access project page with project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +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's landing page + +The project's landing page shows different information depending on +the project's visibility settings and user permissions. + +For public projects, and to members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions): + +- The content of a + [`README` or an index file](repository/#repository-readme-and-index-files) + 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 sees the list of files and directories of the repository. + +For users without permissions to view the project's code, GitLab displays: + +- The wiki homepage, if any. +- The list of issues in the project. |
