diff options
Diffstat (limited to 'doc/user/project')
109 files changed, 1672 insertions, 720 deletions
diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 52c825932fa..85ac641f6e4 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,9 +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 **(PREMIUM)** +# Canary Deployments **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> - [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. 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 @@ -71,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.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core 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/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 4fae10c58eb..9047e564598 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -122,6 +122,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: "iam:CreateInstanceProfile", "iam:CreateServiceLinkedRole", "iam:GetRole", + "iam:listAttachedRolePolicies", "iam:ListRoles", "iam:PassRole", "ssm:GetParameters" diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 8ee9b1f37dd..beb8b71b917 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -189,7 +189,7 @@ To add a Kubernetes cluster to your project, group, or instance: Get the API URL by running this command: ```shell - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}' ``` 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 55467c8a468..a06846e33a6 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -20,7 +20,7 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). - Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - Use [deployment variables](#deployment-variables). - Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). @@ -248,9 +248,17 @@ Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) n [`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the following command in your deployment job script, for Kubernetes to access the registry: -```plaintext -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 - -``` +- Using Kubernetes 1.18+: + + ```shell + 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=client | kubectl apply -f - + ``` + +- Using Kubernetes <1.18: + + ```shell + 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 @@ -308,7 +316,7 @@ combined with either ### Integrations -#### Canary Deployments **(PREMIUM)** +#### Canary Deployments Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) and visualize your canary deployments right inside the Deploy Board, without @@ -316,7 +324,7 @@ the need to leave GitLab. [Read more about Canary Deployments](../canary_deployments.md) -#### Deploy Boards **(PREMIUM)** +#### 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, diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md new file mode 100644 index 00000000000..102001d4f87 --- /dev/null +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -0,0 +1,59 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Container Host Security + +Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can +monitor and (optionally) block activity inside the containers themselves. This is done by leveraging +an integration with Falco to provide the monitoring capabilities and an integration with Pod +Security Policies and AppArmor to provide blocking capabilities. + +## Overview + +Container Host Security can be used to monitor and block activity inside a container as well as to +enforce security policies across the entire Kubernetes cluster. Falco profiles allow for users to +define the activity they want to monitor for and detect. Among other things, this can include system +log entries, process starts, file activity, and network ports opened. AppArmor is used to block any +undesired activity via AppArmor profiles. These profiles are loaded into the cluster when +referenced by Pod Security Policies. + +By default, Container Host Security is deployed into the cluster in monitor mode only, with no +default profiles or rules running out-of-the-box. Activity monitoring and blocking begins only when +users define profiles for these technologies. + +## Installation + +See the [installation guide](quick_start_guide.md) for the recommended steps to install the +Container Host Security capabilities. This guide shows the recommended way of installing Container +Host Security through GMAv2. However, it's also possible to do a manual installation through our +Helm chart. + +## Features + +- Prevent containers from starting as root. +- Limit the privileges and system calls available to containers. +- Monitor system logs, process starts, files read/written/deleted, and network ports opened. +- Optionally block processes from starting or files from being read/written/deleted. + +## Supported container orchestrators + +Kubernetes v1.14+ is the only supported container orchestrator. OpenShift and other container +orchestrators aren't supported. + +## Supported Kubernetes providers + +The following cloud providers are supported: + +- Amazon EKS +- Google GKE + +Although Container Host Security may function on Azure or self-managed Kubernetes instances, it isn't +officially tested and supported on those providers. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_host_security/) +for more information on the product direction of Container Host Security. diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md new file mode 100644 index 00000000000..0c4ec72ed5b --- /dev/null +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -0,0 +1,81 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Getting started with Container Host Security + +The following steps are recommended for installing Container Host Security. Although you can install +some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install +applications through GMAv2 exclusively when using Container Network Security. + +## Installation steps + +The following steps are recommended to install and use Container Host Security through GitLab: + +1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). +1. [Create a group](../../../../group/#create-a-new-group). +1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). +1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). + +1. Install and configure an Ingress node: + + - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). + - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) + into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes + cluster. + +1. [Install and configure Falco](../../../../clusters/applications.md#install-falco-using-gitlab-cicd) + for activity monitoring. +1. [Install and configure AppArmor](../../../../clusters/applications.md#install-apparmor-using-gitlab-cicd) + for activity blocking. +1. [Configure Pod Security Policies](../../../../clusters/applications.md#using-podsecuritypolicy-in-your-deployments) + (required to be able to load AppArmor profiles). + +It's possible to install and manage Falco and AppArmor in other ways, such as installing them +manually in a Kubernetes cluster and then connecting it back to GitLab. These methods aren't +supported or documented. + +## Viewing the logs + +Falco logs can be viewed by running the following command in your Kubernetes cluster: + +```shell +kubectl -n gitlab-managed-apps logs -l app=falco +``` + +## Troubleshooting + +### Trouble connecting to the cluster + +Your CI/CD pipeline may occasionally fail or have trouble connecting to the cluster. Here are some +initial troubleshooting steps that resolve the most common problems: + +1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache) +1. If things still aren't working, a more assertive set of actions may help get things back to a + good state: + + - Stop and [delete the problematic environment](../../../../../ci/environments/#delete-environments-through-the-ui) + in GitLab. + - Delete the relevant namespace in Kubernetes by running + `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. + - Rerun the application project pipeline to redeploy the application. + +### Using GMAv1 with GMAv2 + +When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with +applications being uninstalled or removed from the cluster. This is because GMAv2 actively +uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. +It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the +GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 +applications must be reinstalled after each run of that pipeline. This approach isn't recommended as +it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. +When using Container Network Security, the preferred and recommended path is to install all +necessary components with GMAv2 and the cluster management project. + +**Related documentation links:** + +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md new file mode 100644 index 00000000000..8299844e511 --- /dev/null +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -0,0 +1,70 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Container Network Security + +Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium +NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods +inside the cluster. Container Network Security can be used to enforce L3, L4, and L7 policies and +can prevent an attacker with control over one pod from spreading laterally to access other pods in +the same cluster. Both Ingress and Egress rules are supported. + +By default, Cilium is deployed in Detection-only mode and only logs attack attempts. GitLab provides +a set of out-of-the-box policies as examples and to help users get started. These policies are +disabled by default, as they must usually be customized to match application-specific needs. + +## Installation + +See the [installation guide](quick_start_guide.md) for the recommended steps to install GitLab +Container Network Security. This guide shows the recommended way of installing Container Network +Security through GMAv2. However, it's also possible to install Cilium manually through our Helm +chart. + +## Features + +- 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). +- 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). + +## Supported container orchestrators + +Kubernetes v1.14+ is the only supported container orchestrator. OpenShift and other container +orchestrators aren't supported. + +## Supported Kubernetes providers + +The following cloud providers are supported: + +- Amazon EKS +- Google GKE + +Although Container Network Security may function on Azure or self-managed Kubernetes instances, it +isn't officially tested and supported on those providers. + +## Supported NetworkPolicies + +GitLab only supports the use of CiliumNetworkPolicies. Although generic Kubernetes NetworkPolicies +or other kinds of NetworkPolicies may work, GitLab doesn't test or support them. + +## Managing NetworkPolicies through GitLab vs your cloud provider + +Some cloud providers offer integrations with Cilium or offer other ways to manage NetworkPolicies in +Kubernetes. GitLab Container Network Security doesn't support deployments that have NetworkPolicies +managed by an external provider. By choosing to manage NetworkPolicies through GitLab, you can take +advantage of the following benefits: + +- Support for handling NetworkPolicy infrastructure as code. +- Full revision history and audit log of all changes made. +- Ability to revert back to a previous version at any time. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) +for more information on the product direction of Container Network Security. 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 new file mode 100644 index 00000000000..10f9380a1f2 --- /dev/null +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -0,0 +1,153 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Getting started with Container Network Security + +The following steps are recommended for installing Container Network Security. Although you can +install some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install +applications through GMAv2 exclusively when using Container Network Security. + +## Installation steps + +The following steps are recommended to install and use Container Network Security through GitLab: + +1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/). +1. [Create a group](../../../../group/#create-a-new-group). +1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md). +1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md). + +1. Install and configure an Ingress node: + + - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). + - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) + into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes + cluster. + +1. [Install and configure Cilium](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd). +1. Be sure to restart all pods that were running before Cilium was installed by running this command + in your cluster: + + `kubectl get pods --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HOSTNETWORK:.spec.hostNetwork --no-headers=true | grep '<none>' | awk '{print "-n "$1" "$2}' | xargs -L 1 -r kubectl delete pod` + +It's possible to install and manage Cilium in other ways. For example, you could use the GitLab Helm +chart to install Cilium manually in a Kubernetes cluster, and then connect it back to GitLab. +However, such methods aren't documented or officially supported by GitLab. + +## Managing Network Policies + +Managing NetworkPolicies through GitLab is advantageous over managing the policies in Kubernetes +directly. Kubernetes doesn't provide a GUI editor, a change control process, or a revision history. +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). + +Each method has benefits and drawbacks: + +| | YAML method | UI method (Ultimate/Gold 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. | + +Users are encouraged to choose one of the two methods to manage their policies. If users attempt to +use both methods simultaneously, when the application project pipeline runs the contents of the +NetworkPolicy in the `auto-deploy-values.yaml` file may override policies configured in the UI +editor. + +## Monitoring throughput `**(ULTIMATE)**` + +To view statistics for Container Network Security, you must follow the installation steps above and +configure GitLab integration with Prometheus. Also, if you use custom Helm values for Cilium, you +must enable Hubble with flow metrics for each namespace by adding the following lines to +your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd): +your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd): + +```yaml +global: + hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' +``` + +Additional information about the statistics page is available in the +[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy). + +## Forwarding logs to a SIEM + +Cilium logs can be forwarded to a SIEM or an external logging system through syslog protocol by +installing and configuring Fluentd. Fluentd can be installed through GitLab in two ways: + +- The [GMAv1 method](../../../../clusters/applications.md#fluentd) +- The [GMAv2 method](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd) + +GitLab strongly encourages using only the GMAv2 method to install Fluentd. + +## Viewing the logs + +Cilium logs can be viewed by running the following command in your Kubernetes cluster: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor +``` + +## Troubleshooting + +### Traffic is not being blocked as expected + +By default, Cilium is installed in Audit mode only, meaning that NetworkPolicies log policy +violations but don't block any traffic. To set Cilium to Blocking mode, you must add the following +lines to the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster management project: + +```yaml +config: + policyAuditMode: false + +agent: + monitor: + eventTypes: ["drop"] +``` + +### Traffic is not being allowed as expected + +Keep in mind that when Cilium is set to blocking mode (rather than Audit mode), NetworkPolicies +operate on an allow-list basis. If one or more NetworkPolicies apply to a node, then all traffic +that doesn't match at least one Policy is blocked. To resolve, add NetworkPolicies defining the +traffic that you want to allow in the node. + +### Trouble connecting to the cluster + +Occasionally, your CI/CD pipeline may fail or have trouble connecting to the cluster. Here are some +initial troubleshooting steps that resolve the most common problems: + +1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache). +1. If things still aren't working, a more assertive set of actions may help get things back into a + good state: + + - Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-environments-through-the-ui) in GitLab. + - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. + - Rerun the application project pipeline to redeploy the application. + +### Using GMAv1 with GMAv2 + +When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with +applications being uninstalled or removed from the cluster. This is because GMAv2 actively +uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. +It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the +GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 +applications must be reinstalled after each run of that pipeline. This approach isn't recommended as +it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. +When using Container Network Security, the preferred and recommended path is to install all +necessary components with GMAv2 and the cluster management project. + +**Related documentation links:** + +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md new file mode 100644 index 00000000000..c489a0ddd30 --- /dev/null +++ b/doc/user/project/clusters/protect/index.md @@ -0,0 +1,29 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Protecting your deployed applications + +GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). +These protections are available in the Kubernetes network layer and in the container itself. At +the network layer, the Container Network Security capabilities in GitLab provide basic firewall +functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster +and traffic between pods inside the cluster. Inside the container, Container Host Security provides +Intrusion Detection and Prevention capabilities that can monitor and block activity inside the +containers themselves. + +## Capabilities + +The following capabilities are available to protect deployed applications in Kubernetes: + +- Web Application Firewall + - [Overview](web_application_firewall/index.md) + - [Installation guide](web_application_firewall/quick_start_guide.md) +- Container Network Security + - [Overview](container_network_security/index.md) + - [Installation guide](container_network_security/quick_start_guide.md) +- Container Host Security + - [Overview](container_host_security/index.md) + - [Installation guide](container_host_security/quick_start_guide.md) diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png Binary files differnew file mode 100644 index 00000000000..2dd6df3d37b --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png Binary files differnew file mode 100644 index 00000000000..e88f62a2eba --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png Binary files differnew file mode 100644 index 00000000000..1c99d4f7f96 --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png diff --git a/doc/user/project/clusters/protect/web_application_firewall/index.md b/doc/user/project/clusters/protect/web_application_firewall/index.md new file mode 100644 index 00000000000..6e2e71c6ced --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/index.md @@ -0,0 +1,103 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Web Application Firewall + +WARNING: +The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) +in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) +in GitLab 14.0. + +A web application firewall (or WAF) filters, monitors, and blocks HTTP traffic to +and from a web application. By inspecting HTTP traffic, it can prevent attacks +stemming from web application security flaws. It can be used to detect SQL injection, +Cross-Site Scripting (XSS), Remote File Inclusion, Security Misconfigurations, and +much more. + +## Overview + +GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your +application along with a service and Ingress resource. In the GitLab [Ingress](../../../../clusters/applications.md#ingress) +deployment, the [ModSecurity](https://modsecurity.org/) +module is loaded into Ingress-NGINX by default and monitors the traffic to the applications +which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) +by default. The OWASP CRS detects and logs a wide range of common attacks. + +By default, the WAF is deployed in Detection-only mode and only logs attack attempts. + +## Requirements + +The Web Application Firewall requires: + +- **Kubernetes** + + To enable the WAF, you need: + + - Kubernetes 1.12+. + - A load balancer. You can use NGINX-Ingress by deploying it to your + Kubernetes cluster by either: + - Using the [`nginx-ingress` Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). + - Installing the [Ingress GitLab Managed App](../../../../clusters/applications.md#ingress) with WAF enabled. + +- **Configured Kubernetes objects** + + To use the WAF on an application, you need to deploy the following Kubernetes resources: + + - [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) + - [Service](https://kubernetes.io/docs/concepts/services-networking/service/) + - [Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) + +## Quick start + +If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) for +how to use the WAF with GitLab.com and a Kubernetes cluster on Google Kubernetes Engine (GKE). + +If you are using a self-managed instance of GitLab, you must configure the +[Google OAuth2 OmniAuth Provider](../../../../../integration/google.md) before +you can configure a cluster on GKE. Once this is set up, you can follow the steps on the +[quick start guide](quick_start_guide.md) +to get started. + +NOTE: +This guide shows how the WAF can be deployed using Auto DevOps. The WAF +is available by default to all applications no matter how they are deployed, +as long as they are using Ingress. + +## Network firewall vs. Web Application Firewall + +A network firewall or packet filter looks at traffic at the Network (L3) and Transport (L4) layers +of the [OSI Model](https://en.wikipedia.org/wiki/OSI_model), and denies packets from entry based on +a set of rules regarding the network in general. + +A Web Application Firewall operates at the Application (L7) layer of the OSI Model and can +examine all the packets traveling to and from a specific application. A WAF can set +more advanced rules around threat detection. + +## Features + +ModSecurity is enabled with the [OWASP Core Rule Set (CRS)](https://github.com/coreruleset/coreruleset/) by +default. The OWASP CRS logs attempts to the following attacks: + +- [SQL Injection](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection) +- [Cross-Site Scripting](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS)) +- [Local File Inclusion](https://wiki.owasp.org/index.php/Testing_for_Local_File_Inclusion) +- [Remote File Inclusion](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion) +- [Code Injection](https://wiki.owasp.org/index.php/Code_Injection) +- [Session Fixation](https://wiki.owasp.org/index.php/Session_fixation) +- [Scanner Detection](https://wiki.owasp.org/index.php/Category:Vulnerability_Scanning_Tools) +- [Metadata/Error Leakages](https://wiki.owasp.org/index.php/Improper_Error_Handling) + +It is good to have a basic knowledge of the following: + +- [Kubernetes](https://kubernetes.io/docs/home/) +- [Ingress](https://kubernetes.github.io/ingress-nginx/) +- [ModSecurity](https://www.modsecurity.org/) +- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) + +## Roadmap + +You can find more information on the product direction of the WAF in +[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/). diff --git a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md new file mode 100644 index 00000000000..e9a05b58fec --- /dev/null +++ b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md @@ -0,0 +1,265 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Getting started with the Web Application Firewall + +WARNING: +The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) +in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) +in GitLab 14.0. + +This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after +deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../../../../../topics/autodevops/index.md). + +The GitLab native Kubernetes integration is used, so you do not need +to create a Kubernetes cluster manually using the Google Cloud Platform console. +A simple application is created and deployed based on a GitLab template. + +These instructions also work for a self-managed GitLab instance. However, you +need to ensure your own [runners are configured](../../../../../ci/runners/README.md) and +[Google OAuth is enabled](../../../../../integration/google.md). + +The GitLab Web Application Firewall is deployed with [Ingress](../../../../clusters/applications.md#ingress), +so it is available to your applications no matter how you deploy them to Kubernetes. + +## Configuring your Google account + +Before creating and connecting your Kubernetes cluster to your GitLab project, +you need a Google Cloud Platform account. If you do not already have one, +sign up at <https://console.cloud.google.com>. You need to either sign in with an existing +Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. + +1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). +1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). + +NOTE: +Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab +Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. + +## Creating a new project from a template + +We use a GitLab project templates to get started. As the name suggests, +those projects provide a barebones application built on some well-known frameworks. + +1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select + **New project**. +1. Go to the **Create from template** tab where you can choose for example a Ruby on + Rails, Spring, or NodeJS Express project. + Use the Ruby on Rails template. + +  + +1. Give your project a name, optionally a description, and make it public so that + you can take advantage of the features available in the + [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + +  + +1. Click **Create project**. + +Now that the project is created, the next step is to create the Kubernetes cluster +to deploy this application under. + +## Creating a Kubernetes cluster from within GitLab + +1. On the project's landing page, click **Add Kubernetes cluster** + (note that this option is also available when you navigate to **Operations > Kubernetes**). + +  + +1. On the **Create new cluster on GKE** tab, click **Sign in with Google**. + +  + +1. Connect with your Google account and click **Allow** when asked (this + appears only the first time you connect GitLab with your Google account). + +  + +1. The last step is to provide the cluster details. + 1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster. + (Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.) + 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in. + 1. Enter the number of nodes you want it to have. + 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). + +  + +1. Click **Create Kubernetes cluster**. + +After a couple of minutes, the cluster is created. You can also see its +status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). + +The next step is to install some applications on your cluster that are needed +to take full advantage of Auto DevOps. + +## Install Ingress + +The GitLab Kubernetes integration comes with some +[pre-defined applications](../../index.md#installing-applications) +for you to install. + + + +For this guide, we need to install Ingress. Ingress provides load balancing, +SSL termination, and name-based virtual hosting, using NGINX behind +the scenes. Make sure to switch the toggle to the enabled position before installing. + +Both logging and blocking modes are available for WAF. While logging mode is useful for +auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress. + + + +After Ingress is installed, wait a few seconds and copy the IP address that +is displayed in order to add in your base **Domain** at the top of the page. For +the purpose of this guide, we use the one suggested by GitLab. Once you have +filled in the domain, click **Save changes**. + + + +Prometheus should also be installed. It is an open-source monitoring and +alerting system that is used to supervise the deployed application. +Installing GitLab Runner is not required as we use the shared runners that +GitLab.com provides. + +## Enabling Auto DevOps (optional) + +Starting with GitLab 11.3, Auto DevOps is enabled by default. However, it is possible to disable +Auto DevOps at both the instance-level (for self-managed instances) and the group-level. +Follow these steps if Auto DevOps has been manually disabled: + +1. Navigate to **Settings > CI/CD > Auto DevOps**. +1. Select **Default to Auto DevOps pipeline**. +1. Select the [continuous deployment strategy](../../../../../topics/autodevops/index.md#deployment-strategy) + which automatically deploys the application to production once the pipeline + successfully runs on the `master` branch. +1. Click **Save changes**. + +  + +Once you complete all the above and save your changes, a new pipeline is +automatically created. To view the pipeline, go to **CI/CD > Pipelines**. + + + +The next section explains what each pipeline job does. + +## Deploying the application + +By now you should see the pipeline running, but what is it running exactly? + +To navigate inside the pipeline, click its status badge (its status should be "Running"). +The pipeline is split into a few stages, each running a couple of jobs. + + + +In the **build** stage, the application is built into a Docker image and then +uploaded to your project's [Container Registry](../../../../packages/container_registry/index.md) +([Auto Build](../../../../../topics/autodevops/stages.md#auto-build)). + +In the **test** stage, GitLab runs various checks on the application. + +The **production** stage is run after the tests and checks finish, and it automatically +deploys the application in Kubernetes ([Auto Deploy](../../../../../topics/autodevops/stages.md#auto-deploy)). + +The **production** stage creates Kubernetes objects +like a Deployment, Service, and Ingress resource. The +application is monitored by the WAF automatically. + +## Validating Ingress is running ModSecurity + +Now we can make sure that Ingress is running properly with ModSecurity and send +a request to ensure our application is responding correctly. You must connect to +your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). + +1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. + + This is done by running the following commands: + + ```shell + $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' + ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running + + $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;' + modsecurity on; + ``` + +1. Verify the Rails application has been installed properly. + + ```shell + $ kubectl get ns + auto-devv-2-16730183-production Active + + $ kubectl get pods -n auto-devv-2-16730183-production + NAME READY STATUS RESTARTS + production-5778cfcfcd-nqjcm 1/1 Running 0 + production-postgres-6449f8cc98-r7xgg 1/1 Running 0 + ``` + +1. To make sure the Rails application is responding, send a request to it by running: + + ```shell + $ kubectl get ing -n auto-devv-2-16730183-production + NAME HOSTS PORTS + production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 + + $ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2 + <body> + <p>You're on Rails!</p> + </body> + ``` + +Now that we have confirmed our system is properly setup, we can go ahead and test +the WAF with OWASP CRS! + +## Testing out the OWASP Core Rule Set + +Now let's send a potentially malicious request, as if we were a scanner, +checking for vulnerabilities within our application and examine the ModSecurity logs: + +```shell +$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 +<body> + <p>You're on Rails!</p> +</body> + +$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /var/log/modsec/audit.log | grep 'absinthe' +{ + "message": "Found User-Agent associated with security scanner", + "details": { + "match": "Matched \"Operator `PmFromFile' with parameter `scanners-user-agents.data' against variable `REQUEST_HEADERS:user-agent' (Value: `absinthe' )", + "reference": "o0,8v84,8t:lowercase", + "ruleId": "913100", + "file": "/etc/nginx/owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf", + "lineNumber": "33", + "data": "Matched Data: absinthe found within REQUEST_HEADERS:user-agent: absinthe", + "severity": "2", + "ver": "OWASP_CRS/3.2.0", + "rev": "", + "tags": ["application-multi", "language-multi", "platform-multi", "attack-reputation-scanner", "OWASP_CRS", "OWASP_CRS/AUTOMATION/SECURITY_SCANNER", "WASCTC/WASC-21", "OWASP_TOP_10/A7", "PCI/6.5.10"], + "maturity": "0", + "accuracy": "0" + } +} +``` + +You can see that ModSecurity logs the suspicious behavior. By sending a request +with the `User Agent: absinthe` header, which [absinthe](https://github.com/cameronhotchkies/Absinthe), +a tool for testing for SQL injections uses, we can detect that someone was +searching for vulnerabilities on our system. Detecting scanners is useful, because we +can learn if someone is trying to exploit our system. + +## Conclusion + +You can now see the benefits of a using a Web Application Firewall. +ModSecurity and the OWASP Core Rule Set, offer many more benefits. +You can explore them in more detail: + +- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/) +- [ModSecurity](https://www.modsecurity.org/) +- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) +- [AutoDevOps](../../../../../topics/autodevops/index.md) diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 332c1f35d89..8572ab850e4 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -103,7 +103,7 @@ the components outlined above and the pre-loaded demo runbook. Enter these values, maintaining the single quotes as follows: ```sql - PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' + PRIVATE_TOKEN = '<your_access_token>' PROJECT_ID = '1234567' ``` diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index fa80bd6423b..d734db6bac9 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,155 +1,8 @@ --- -stage: Protect -group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'protect/index.md' --- -# Securing your deployed applications +This document was moved to [another location](protect/index.md). -GitLab makes it easy to secure applications deployed in [connected Kubernetes clusters](index.md). -You can benefit from the protection of a [Web Application Firewall](../../../topics/web_application_firewall/quick_start_guide.md), -[Network Policies](../../../topics/autodevops/stages.md#network-policy), -and [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd). - -This page contains full end-to-end steps and instructions to connect your cluster to GitLab and -install these features, whether or not your applications are deployed through GitLab CI/CD. If you -use [Auto DevOps](../../../topics/autodevops/index.md) -to build and deploy your application with GitLab, see the documentation for the respective -[GitLab Managed Applications](../../clusters/applications.md) -above. - -## Overview - -At a high level, the required steps include the following: - -- Connect the cluster to GitLab. -- Set up one or more runners. -- Set up a cluster management project. -- Install a Web Application Firewall, and/or Network Policies, and/or Container Host - Security. -- Install Prometheus to get statistics and metrics in the - [threat monitoring](../../application_security/threat_monitoring/) - dashboard. - -### Requirements - -Minimum requirements (depending on the GitLab Manage Application you want to install): - -- Your cluster is connected to GitLab (ModSecurity, Cilium, and Falco). -- At least one runner is installed (Cilium and Falco only). - -### Understanding how GitLab Managed Apps are installed - -NOTE: -These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm -command runner pod in the cluster. - -You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab -uses Sidekiq (a background processing service) to facilitate this. - -```mermaid - sequenceDiagram - autonumber - GitLab->>+Sidekiq: Install a GitLab Managed App - Sidekiq->>+Kubernetes: Helm install - Kubernetes-->>-Sidekiq: Installation complete - Sidekiq-->>-GitLab: Refresh UI -``` - -Although this installation method is easier because it's a point-and-click action in the user -interface, it's inflexible and harder to debug. If something goes wrong, you can't see the -deployment logs. The Web Application Firewall feature uses this installation method. - -However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103)) -don't use Sidekiq to deploy. All the applications are deployed using a GitLab CI/CD pipeline and -therefore, by runners. - -```mermaid -sequenceDiagram - autonumber - GitLab->>+GitLab: Trigger pipeline - GitLab->>+Runner: Run deployment job - Runner->>+Kubernetes: Helm install - Kubernetes-->>-Runner: Installation is complete - Runner-->>-GitLab: Report job status and update pipeline -``` - -Debugging is easier because you have access to the raw logs of these jobs (the Helm Tiller output is -available as an artifact in case of failure), and the flexibility is much better. Since these -deployments are only triggered when a pipeline is running (most likely when there's a new commit in -the cluster management repository), every action has a paper trail and follows the classic merge -request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App, and Container -Host Security (Falco) are deployed with this model. - -## Connect the cluster to GitLab - -To deploy GitLab Managed Apps to your cluster, you must first -[add your cluster](add_remove_clusters.md) -to GitLab. Then [install](../../clusters/applications.md#install-with-one-click) -the Web Application Firewall from the project or group Kubernetes page. - -Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a -cluster independent of the applications that use the cluster. - -## Set up a runner - -To install CI/CD-based GitLab Managed Apps, a pipeline using a runner must be running in -GitLab. You can [install a runner](../../clusters/applications.md#gitlab-runner) -in the Kubernetes cluster added in the previous step, or use one of the shared runners provided by -GitLab if you're using GitLab.com. - -With your cluster connected to GitLab and a runner in place, you can proceed to the next -steps and start installing the Cilium and Falco GitLab Managed Apps to secure your applications -hosted on this cluster. - -## Create a Cluster Management Project - -A [Cluster Management Project](../../clusters/management_project.md) -is a GitLab project that contains a `.gitlab-ci.yml` file to deploy GitLab Managed Apps to your -cluster. This project runs the required charts with the Kubernetes -[`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) -privileges. - -The creation of this project starts like any other GitLab project. Use an empty -project and add a `gitlab-ci.yml` file at the root, containing this template: - -```yaml -include: - - template: Managed-Cluster-Applications.gitlab-ci.yml -``` - -To make this project a Cluster Management Project, follow these -[instructions](../../clusters/management_project.md#selecting-a-cluster-management-project). -This project can be designated as such even if your application isn't hosted on GitLab. In this -case, create a new empty project where you can select your newly created Cluster Management Project. - -## Install GitLab Container Network Policy - -GitLab Container Network Policy is based on [Cilium](https://cilium.io/). To -install the Cilium GitLab Managed App, add a -`.gitlab/managed-apps/config.yaml` file to your Cluster Management project: - -```yaml -# possible values are gke, eks or you can leave it blank -clusterType: gke - -cilium: - installed: true -``` - -Your application doesn't have to be managed or deployed by GitLab to leverage this feature. -[Read more](../../clusters/applications.md#install-cilium-using-gitlab-cicd) -about configuring Container Network Policy. - -## Install GitLab Container Host Security - -Similarly, you can install Container Host Security, based on -[Falco](https://falco.org/), in your `.gitlab/managed-apps/config.yaml`: - -```yaml -falco: - installed: true -``` - -[Read more](../../clusters/applications.md#install-falco-using-gitlab-cicd) -about configuring Container Host Security. +<!-- This redirect file can be deleted after <2021-04-01>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index fcbf85121b2..043c5e4ca79 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -560,7 +560,6 @@ Or: By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. -12345678901234567890123456789012345678901234567890123456789012345678901234567890 The simplest way to accomplish this is to use Certbot to [manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index d0e89400d88..63ea84e42c9 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -225,6 +225,52 @@ 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. + +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: + +```plaintext +[Documentation] +*.md @root + +[Ruby] +*.rb @root + +^[Go] +*.go @root +``` + +The optional code owners section will be displayed 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. + +For example, the code owners of the "Documentation" section below will still be required to approve merge requests: + +```plaintext +[Documentation] +*.md @root + +[Ruby] +*.rb @root + +^[Go] +*.go @root + +^[Documentation] +*.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 +[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. + ## Example `CODEOWNERS` file ```plaintext diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 33bec99767a..831a8803622 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,9 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(PREMIUM)** +# Deploy Boards **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [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. 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 @@ -53,8 +54,8 @@ specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the environments list, verify that what's running in staging is what you think is running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production. -- You trigger a deploy, and you've got lots of containers to upgrade so you know - it'll take a while (you've also throttled your deploy to only take down X +- You trigger a deploy, and you have many containers to upgrade so you know + this takes a while (you've also throttled your deploy to only take down X containers at a time). But you need to tell someone when it's deployed, so you go to the environments list, look at the production environment to see what the progress is in real-time as each pod is rolled. @@ -75,8 +76,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. Have a Kubernetes cluster up and running. NOTE: - If you are using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render + If you're using OpenShift, ensure that you're using the `Deployment` resource + instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards don't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). @@ -84,7 +85,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. [Configure GitLab Runner](../../ci/runners/README.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the - cluster. The Kubernetes namespace is of particular note as you will need it + cluster. The Kubernetes namespace is of particular note as you need it for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the @@ -94,7 +95,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 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` template which has predefined stages and commands to use, and automatically - applies the annotations. Each project will need to have a unique namespace in + applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes. @@ -105,7 +106,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. - If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: + If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**:  @@ -141,7 +142,7 @@ spec: app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} ``` -The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. +The annotations are applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. NOTE: The YAML file is static. If you apply it using `kubectl apply`, you must diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 39b790544c1..93ed1030e1f 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -92,7 +92,7 @@ There are three lists of Project Deploy Keys:  -After you add a key, it will be enabled for this project by default, and it'll appear +After you add a key, it's enabled for this project by default and it appears in the **Enabled deploy keys** tab. In the **Privately accessible deploy keys** tab, you can enable a private key which @@ -111,7 +111,7 @@ and `read-write` access. NOTE: If you have enabled a privately or publicly accessible or deploy key for your project, and if you then update the access level for this key from `read-only` to -`read-write`, the change will be only for the **current project**. +`read-write`, the change is only for the **current project**. ### Public deploy keys @@ -131,7 +131,7 @@ Instance administrators can add public deploy keys:  -After adding a key, it will be available to any shared systems. Project maintainers +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. NOTE: @@ -155,8 +155,8 @@ until a project maintainer chooses to make use of it. ### Deploy Key cannot push to a protected branch -If the owner of this deploy key does not have access to a [protected -branch](../protected_branches.md), then this deploy key won't have access to +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 the branch either. In addition to this, choosing the **No one** value in [the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) means that no users **and** no services using deploy keys can push to that selected branch. diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png Binary files differindex 83f59b8f6f0..4ab6a45aee1 100644 --- a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png +++ b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ac19c44c58a..5a62730d989 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -36,7 +36,7 @@ project. Alternatively, you can also create [group-scoped deploy tokens](#group- 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Select **Create deploy token**. 1. Save the deploy token somewhere safe. After you leave or refresh - the page, **you won't be able to access it again**. + the page, **you can't access it again**.  @@ -89,7 +89,7 @@ Replace `<username>` and `<deploy_token>` with the proper values. ### Read Container Registry images -To read the container registry images, you'll need to: +To read the container registry images, you must: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. @@ -106,7 +106,7 @@ pull images from your Container Registry. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -To push the container registry images, you'll need to: +To push the container registry images, you must: 1. Create a Deploy Token with `write_registry` as a scope. 1. Take note of your `username` and `token`. @@ -123,7 +123,7 @@ push images to your Container Registry. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -To pull packages in the GitLab package registry, you'll need to: +To pull packages in the GitLab package registry, you must: 1. Create a Deploy Token with `read_package_registry` as a scope. 1. Take note of your `username` and `token`. @@ -134,7 +134,7 @@ To pull packages in the GitLab package registry, you'll need to: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -To upload packages in the GitLab package registry, you'll need to: +To upload packages in the GitLab package registry, you must: 1. Create a Deploy Token with `write_package_registry` as a scope. 1. Take note of your `username` and `token`. @@ -160,7 +160,7 @@ To use a group deploy token: 1. Use it the same way you use a project deploy token when [cloning a repository](#git-clone-a-repository). -The scopes applied to a group deploy token (such as `read_repository`) will +The scopes applied to a group deploy token (such as `read_repository`) apply consistently when cloning the repository of related projects. ### GitLab Deploy Token @@ -168,7 +168,7 @@ apply consistently when cloning the repository of related projects. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8. There's a special case when it comes to Deploy Tokens. If a user creates one -named `gitlab-deploy-token`, the username and token of the Deploy Token will be +named `gitlab-deploy-token`, the username and token of the Deploy Token is automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, respectively. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index db2631f9596..3108bdda7a0 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -108,7 +108,7 @@ you should be fine.  After you add the description, hit **Save changes** for the settings to take -effect. Now, every time a new merge request or issue is created, it is +effect. Now, every time a new merge request or issue is created, it is pre-filled with the text you entered in the template(s). ## Description template example diff --git a/doc/user/project/img/canary_weight.png b/doc/user/project/img/canary_weight.png Binary files differindex e6544358c15..fe17c62bdea 100644 --- a/doc/user/project/img/canary_weight.png +++ b/doc/user/project/img/canary_weight.png diff --git a/doc/user/project/img/description_templates_issue_settings.png b/doc/user/project/img/description_templates_issue_settings.png Binary files differindex 657b6ae1269..7f354f7c288 100644 --- a/doc/user/project/img/description_templates_issue_settings.png +++ b/doc/user/project/img/description_templates_issue_settings.png 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 differnew file mode 100644 index 00000000000..7a5a2fab6e3 --- /dev/null +++ b/doc/user/project/img/optional_code_owners_sections_v13_8.png diff --git a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png Binary files differindex 6eda7a671b2..ccd23dbe160 100644 --- a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png +++ b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png diff --git a/doc/user/project/img/service_desk_custom_email_address_v13_0.png b/doc/user/project/img/service_desk_custom_email_address_v13_0.png Binary files differdeleted file mode 100644 index 3789e039904..00000000000 --- a/doc/user/project/img/service_desk_custom_email_address_v13_0.png +++ /dev/null diff --git a/doc/user/project/img/service_desk_enabled.png b/doc/user/project/img/service_desk_enabled.png Binary files differdeleted file mode 100644 index 33d51227e5f..00000000000 --- a/doc/user/project/img/service_desk_enabled.png +++ /dev/null diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 8b6d86b14c9..c135b1be54a 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -63,7 +63,7 @@ must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. - Have a GitHub account with a publicly visible [primary email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) - on their profile that matches their GitLab account's email address. + on their profile that matches their GitLab account's primary or secondary email address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8344baebd82..ccf4b6cb303 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -37,7 +37,7 @@ integration settings. Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). +docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). To enable the GitLab service for your Slack team: diff --git a/doc/user/project/integrations/img/webhooks_ssl.png b/doc/user/project/integrations/img/webhooks_ssl.png Binary files differdeleted file mode 100644 index e5777a2e99b..00000000000 --- a/doc/user/project/integrations/img/webhooks_ssl.png +++ /dev/null diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index f15a5ee4429..3c91fd3549f 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -30,6 +30,6 @@ The following Jira integrations allow different types of cross-referencing betwe | 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. | | Mention of Jira issue ID in GitLab branch names is reflected in Jira issue | No | Yes, in the issue’s Development panel | -| Record Jira time tracking info against an issue | No | Yes. Time can be specified via Jira Smart Commits. | +| 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 | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 9d7960790ff..959c4cc623b 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -199,7 +199,6 @@ to integrate with. ### Precedence with multiple Prometheus configurations -12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you can use only one: diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index d8b51e8b777..47a44e53b47 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Webhooks -Project webhooks allow you to trigger a URL if for example new code is pushed or +Project webhooks allow you to trigger a percent-encoded URL if, for example, new code is pushed or a new issue is created. You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. @@ -28,32 +28,15 @@ notify bug tracking systems. Webhooks can be used to update an external issue tracker, trigger CI jobs, update a backup mirror, or even deploy to your production server. -They are available **per project** for GitLab Community Edition, -and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page at your project's **Settings > Webhooks**. +Webhooks are available: + +- Per project, at a project's **Settings > Webhooks** menu. **(CORE)** +- Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** NOTE: On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. -## Version history - -Starting from GitLab 8.5: - -- the `repository` key is deprecated in favor of the `project` key -- the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key -- the `project.http_url` key is deprecated in favor of the `project.git_http_url` key - -Starting from GitLab 11.1, the logs of webhooks are automatically removed after -one month. - -Starting from GitLab 11.2: - -- The `description` field for issues, merge requests, comments, and wiki pages - is rewritten so that simple Markdown image references (like - ``) have their target URL changed to an absolute URL. See - [image URL rewriting](#image-url-rewriting) for more details. - ## Possible uses for webhooks - You can set up a webhook in GitLab to send a notification to @@ -91,8 +74,6 @@ be self-signed. You can turn this off in the webhook settings in your GitLab projects. - - ## Branch filtering > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. @@ -115,6 +96,10 @@ attribute only contains the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. +NOTE: +If a branch creation push event is generated without new commits being introduced, the +`commits` attribute in the payload is empty. + Also, if a single push includes changes for more than three (by default, depending on [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) branches, this hook isn't executed. @@ -276,6 +261,7 @@ X-Gitlab-Event: Issue Hook "object_kind": "issue", "event_type": "issue", "user": { + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", @@ -439,9 +425,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -519,9 +507,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -646,9 +636,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -752,9 +744,11 @@ X-Gitlab-Event: Note Hook { "object_kind": "note", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project_id": 5, "project":{ @@ -828,9 +822,11 @@ X-Gitlab-Event: Merge Request Hook { "object_kind": "merge_request", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" }, "project": { "id": 1, @@ -989,9 +985,11 @@ X-Gitlab-Event: Wiki Page Hook { "object_kind": "wiki_page", "user": { + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "email": "admin@example.com" }, "project": { "id": 1, @@ -1080,6 +1078,7 @@ X-Gitlab-Event: Pipeline Hook "url": "http://192.168.64.1:3005/gitlab-org/gitlab-test/merge_requests/1" }, "user":{ + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", @@ -1121,9 +1120,11 @@ X-Gitlab-Event: Pipeline Hook "manual": true, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": null, "artifacts_file":{ @@ -1143,9 +1144,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": { "id":380987, @@ -1170,9 +1173,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": { "id":380987, @@ -1197,9 +1202,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": { "id":380987, @@ -1224,9 +1231,11 @@ X-Gitlab-Event: Pipeline Hook "manual": false, "allow_failure": false, "user":{ + "id": 1, "name": "Administrator", "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "runner": null, "artifacts_file":{ @@ -1273,7 +1282,8 @@ X-Gitlab-Event: Job Hook "id": 3, "name": "User", "email": "user@gitlab.com", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" }, "commit": { "id": 2366, @@ -1349,6 +1359,7 @@ X-Gitlab-Event: Deployment Hook }, "short_sha": "279484c0", "user": { + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", @@ -1362,11 +1373,18 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. -### Member events +### Group member events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. -Triggered when a user is added as a group member. +Member events are triggered when: + +- A user is added as a group member +- The access level of a user has changed +- The expiration date for user access has been updated +- A user has been removed from the group + +#### Add member to group **Request Header**: @@ -1394,6 +1412,62 @@ X-Gitlab-Event: Member Hook } ``` +#### Update member access level or expiration date + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-12T08:48:19Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Developer", + "group_plan": null, + "expires_at": "2020-12-20T00:00:00Z", + "event_name": "user_update_for_group" +} +``` + +#### Remove member from group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-12T08:52:34Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_remove_from_group" +} +``` + ### Feature Flag events Triggered when a feature flag is turned on or off. @@ -1428,6 +1502,7 @@ X-Gitlab-Event: Feature Flag Hook "http_url":"http://example.com/gitlabhq/gitlab-test.git" }, "user": { + "id": 1, "name": "Administrator", "username": "root", "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", @@ -1554,7 +1629,7 @@ Markdown features, like link labels. ## Testing webhooks You can trigger the webhook manually. Sample data from the project is used. -> For example: for triggering `Push Events` your project should have at least one commit. +For example, for triggering `Push Events` your project should have at least one commit.  diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e0f66013454..7119970fca0 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards +# 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). @@ -233,17 +233,18 @@ advanced functionality is present in [higher tiers only](https://about.gitlab.co ### Configurable issue boards **(STARTER)** -> [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. +> - [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. -An issue board can be associated with a GitLab [Milestone](milestones/index.md#milestones), -[Labels](labels.md), Assignee and Weight +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), which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need.  You can define the scope of your board when creating it or by clicking the **Edit board** button. -After a milestone, assignee or weight is assigned to an issue board, you can no longer +After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. @@ -320,7 +321,8 @@ As in other list types, click the trash icon to remove a list. ### Group issues in swimlanes **(PREMIUM)** -> Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. @@ -336,6 +338,19 @@ To group issues by epic in an issue board:  +To edit an issue without leaving this view, select the issue card (not its title), and a sidebar +appears on the right. There you can see and edit the issue's: + +- Title +- Assignees +- Epic **PREMIUM** +- Milestone +- Time tracking value (view only) +- Due date +- Labels +- Weight +- Notifications setting + You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: - To reorder an issue, drag it to the new position within a list. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 02cb0313a74..d4fbc4fb10b 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -29,8 +29,8 @@ confidential checkbox and hit **Save changes**. There are two ways to change an issue's confidentiality. -The first way is to edit the issue and mark/unmark the confidential checkbox. -Once you save the issue, it will change the confidentiality of the issue. +The first way is to edit the issue and toggle the confidentiality checkbox. +After you save the issue, the confidentiality of the issue is updated. The second way is to locate the Confidentiality section in the sidebar and click **Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. @@ -46,20 +46,19 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: -If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), -you won't be able to see the confidential issues at all. - There are a few things that visually separate a confidential issue from a regular one. In the issues index page view, you can see the eye-slash icon next to the issues that are marked as confidential.  +If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +you cannot see confidential issues at all. + --- Likewise, while inside the issue, you can see the eye-slash icon right next to -the issue number, but there is also an indicator in the comment area that the +the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential.  @@ -83,7 +82,7 @@ project's search results respectively. | Maintainer access | Guest access | | :-----------: | :----------: | -|  |  | +|  |  | ## Merge Requests for Confidential Issues @@ -93,24 +92,24 @@ To help prevent confidential information being leaked from a public project in the process of resolving a confidential issue, confidential issues can be resolved by creating a merge request from a private fork. -The merge request created will target the default branch of the private fork, +The created merge request targets the default branch of the private fork, not the default branch of the public upstream project. This prevents the merge request, branch, and commits entering the public repository, and revealing -confidential information prematurely. When the confidential commits are ready -to be made public, this can be done by opening a merge request from the private -fork to the public upstream project. +confidential information prematurely. To make a confidential commit public, +open a merge request from the private fork to the public upstream project. -NOTE: -If you create a long-lived private fork in the same group or in a sub-group of -the original upstream, all the users with Developer membership to the public -project will also have the same permissions in the private project. This way, -all the Developers, who have access to view confidential issues, will have a -streamlined workflow for fixing them. +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 +Permissions are inherited from parent groups. When private forks are created +in the same group or sub-group 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. ### How it works On a confidential issue, a **Create confidential merge request** button is -available. Clicking on it will open a dropdown where you can choose to +available. Clicking on it opens a dropdown where you can choose to **Create confidential merge request and branch** or **Create branch**: | Create confidential merge request | Create branch | @@ -121,12 +120,12 @@ The **Project** dropdown includes the list of private forks the user is a member of as at least a Developer and merge requests are enabled. Whenever the **Branch name** and **Source (branch or tag)** fields change, the -availability of the target or source branch will be checked. Both branches should -be available in the private fork selected. +availability of the target and source branch are checked. Both branches should +be available in the selected private fork. -By clicking the **Create confidential merge request** button, GitLab will create +By clicking the **Create confidential merge request** button, GitLab creates the branch and merge request in the private fork. When you choose -**Create branch**, GitLab will only create the branch. +**Create branch**, GitLab creates only the branch. -Once the branch is created in the private fork, developers can now push code to +After the branch is created in the private fork, developers can push code to that branch to fix the confidential issue. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index b5d3b71e679..250fa618dd8 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -31,10 +31,9 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -NOTE: -Linking your first commit to your issue is going to be relevant +Linking your first commit to your issue is relevant for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -It will measure the time taken for planning the implementation of that issue, +It measures the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. ## From Related Issues @@ -45,7 +44,7 @@ issues regarding the same topic. You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages). -When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification +When mentioning issue `#111` in issue `#222`, issue `#111` also displays a notification in its tracker. That is, you only need to mention the relationship once for it to display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests). @@ -56,8 +55,8 @@ display in both issues. The same is valid when mentioning issues in [merge reque Mentioning issues in merge request comments works exactly the same way as they do for [related issues](#from-related-issues). -When you mention an issue in a merge request description, it will simply -[link the issue and merge request together](#from-related-issues). Additionally, +When you mention an issue in a merge request description, it +[links the issue and merge request together](#from-related-issues). Additionally, you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically) as soon as the merge request is merged. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 023a8ee57bc..e7cd1377603 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data wis 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: +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/due_dates.md b/doc/user/project/issues/due_dates.md index 63cd784333a..34e9340067c 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -11,14 +11,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. Due dates can be used in issues to keep track of deadlines and make sure features are -shipped on time. Users must have at least [Reporter permissions](../../permissions.md) -to be able to edit them, but they can be seen by everybody with permission to view -the issue. +shipped on time. Users need at least [Reporter permissions](../../permissions.md) +to be able to edit the due date. All users with permission to view +the issue can view the due date. ## Setting a due date -When creating or editing an issue, you can click in the **due date** field and a calendar -will appear to help you choose the date you want. To remove the date, select the date +When creating an issue, select the **Due date** field to make a calendar +appear for choosing the date. To remove the date, select the date text and delete it. The date is related to the server's timezone, not the timezone of the user setting the due date. @@ -37,18 +37,17 @@ The last way to set a due date is by using [quick actions](../quick_actions.md), ## Making use of due dates -Issues that have a due date can be easily seen in the issue tracker, -displaying a date next to them. Issues where the date is overdue will have -the icon and the date colored red. You can sort issues by those that are -`Due soon` or `Due later` from the dropdown menu on the right. - - +You can see issues with their due dates in the [issues list](index.md#issues-list). +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}**). Due dates also appear in your [to-do list](../../todos.md).  -The day before an open issue is due, an email will be sent to all participants +The day before an open issue is due, an email is sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the server's timezone. diff --git a/doc/user/project/issues/img/due_dates_issues_index_page.png b/doc/user/project/issues/img/due_dates_issues_index_page.png Binary files differdeleted file mode 100644 index 94679436b32..00000000000 --- a/doc/user/project/issues/img/due_dates_issues_index_page.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 05e7eb3021a..74311eefd83 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -22,8 +22,8 @@ their implementation between: 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, but if you have multiple projects in a group, -you can also view all the issues collectively at the group level. +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:** @@ -91,9 +91,13 @@ must be set. ## Viewing and managing issues -While you can view and manage the full details of an issue on the [issue page](#issue-page), -you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics). **(PREMIUM)** +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)**. Key actions for issues include: @@ -117,14 +121,17 @@ and modify them if you have the necessary [permissions](../../permissions.md). 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). -### Issues list +### Issues List + + + +On 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. -On the Issues List, you can view all issues in the current project, or from multiple -projects when opening the Issues List from the higher-level group context. Filter the -issue list with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), -including specific metadata, such as label(s), assignees(s), status, and more. From this +You can filter the Issues List with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), +including specific metadata, such as labels, assignees, status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page @@ -140,21 +147,21 @@ You can sort a list of issues in several ways, for example by issue creation dat labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using highly customizable workflows. -You can reorder issues within a column. If you drag an issue card to another column, its -associated label or assignee will change to match that of the new column. The entire +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. ### Design Management With [Design Management](design_management.md), you can upload design -assets to issues and view them all together to easily share and -collaborate with your team. +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 by tracking groups of issues that share a theme, across +efficiently and with less effort. Epics track groups of issues that share a theme, across projects and milestones. ### Related issues @@ -179,10 +186,10 @@ message in the Activity stream about the reference, with a link to the other iss To prevent duplication of issues for the same topic, GitLab searches for similar issues when new issues are being created. -When typing in the title in the **New Issue** page, GitLab searches titles and descriptions -across all issues the user has access to in the current project. Up to five similar issues, -sorted by most recently updated, are displayed below the title box. Note that this feature -requires [GraphQL](../../../api/graphql/index.md) to be enabled. +As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions +across all issues to in the current project. Only issues you have access to are returned. +Up to five similar issues, sorted by most recently updated, are displayed below the title box. +[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature.  @@ -193,8 +200,8 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. > - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. -To help you track the status of your issues, you can assign a status to each issue to flag work -that's progressing as planned or needs attention to keep on schedule: +To help you track issue statuses, you can assign a status to each issue. +This marks issues as progressing as planned or needs attention to keep on schedule: - **On track** (green) - **Needs attention** (amber) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2520a562f1e..4c8630581f5 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -35,6 +35,7 @@ The numbers in the image correspond to the following features: - **12.** [Participants](#participants) - **13.** [Notifications](#notifications) - **14.** [Reference](#reference) +- [Issue email](#email) - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) @@ -174,6 +175,13 @@ for the issue. Notifications are automatically enabled after you participate in `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and `xxx` is the issue number. +### Email + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. + +Guest users can see a button in the right sidebar to copy the email address for the issue. +Sending an email to this address creates a comment containing the email body. + ### Edit Clicking this icon opens the issue for editing. All the fields which diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 03060ca720c..ef860df054e 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -19,16 +19,16 @@ Key actions for issues include: ## Create a new issue -When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), +When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), as illustrated below. If you know the values you want to assign to an issue, you can use the -[Quick actions](../quick_actions.md) feature to input values, instead of selecting them from lists. +[Quick actions](../quick_actions.md) feature to input values. While creating an issue, you can associate it to an existing epic from current group by selecting it using **Epic** dropdown. ### Accessing the New Issue form -There are many ways to get to the New Issue form from within a project: +There are many ways to get to the New Issue form from a project's page: - Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: @@ -75,9 +75,8 @@ using the dropdown button at the top-right of the page.  -We'll keep track of the project you selected most recently, and use it as the default -for your next visit. This should save you a lot of time and clicks, if you mostly -create issues for the same project. +The project you selected most recently becomes the default for your next visit. +This should save you a lot of time and clicks, if you mostly create issues for the same project.  @@ -90,22 +89,22 @@ the appropriate project and followed up from there. ### New issue via email A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured. +**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) +configured and there is at least one issue in the issue list.  When you click this link, an email address is generated and displayed, which should be used by **you only**, to create issues in this project. You can save this address as a -contact in your email client for easy access. +contact in your email client for quick access. WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they -were you. If the address is compromised, or you'd like it to be regenerated for -any reason, click **Email a new issue to this project** again and click the reset link. +were you. If the address is compromised, or you want to regenerate it, +click **Email a new issue to this project**, followed by **reset it**. -Sending an email to this address will create a new issue in your name for +Sending an email to this address creates a new issue associated with your account for this project, where: - The email subject becomes the issue title. @@ -118,15 +117,15 @@ older format is still supported, allowing existing aliases or contacts to contin ### New issue via URL with prefilled fields -You can link directly to the new issue page for a given project, with prefilled -field values using query string parameters in a URL. This is useful for embedding -a URL in an external HTML page, and also certain scenarios where you want the user to -create an issue with certain fields prefilled. +To link directly to the new issue page with prefilled fields, use query +string parameters in a URL. You can embed a URL in an external +HTML page, or create issues with certain +fields prefilled. The title, description, description template, and confidential fields can be prefilled using this method. You cannot pre-fill both the description and description template -fields in the same URL (since a description template also populates the description -field). +fields in the same URL because a description template also populates the description +field. | Field | URL Parameter Name | Notes | |----------------------|-----------------------|-------------------------------------------------------| @@ -147,9 +146,9 @@ Follow these examples to form your new issue URL with prefilled fields. ## Moving Issues -Moving an issue will copy it to a new location (project), and close it in the old project, -but it will not be deleted. There will also be a system note added to both issues -indicating where it came from and went to. +Moving an issue copies it to the target project, and closes it in the originating project. +The original issue is not deleted. A system note, which indicates +where it came from and went to, is added to both issues. The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. @@ -157,7 +156,9 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i ### Moving Issues in Bulk -If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. +If you have advanced technical skills you can also bulk move all the issues from +one project to another in the rails console. The below script moves all issues +that are not in status **closed** from one project to another. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. @@ -193,23 +194,18 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: -For performance reasons, automatic issue closing is disabled for the very first -push from an existing repository. - -When a commit or merge request resolves one or more issues, it is possible to have -these issues closed automatically when the commit or merge request reaches the project's -default branch. +When a commit or merge request resolves issues, the issues +can be closed automatically when the commit reaches the project's default branch. If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), -all issues referenced in the matched text will be closed. This happens when the commit +all issues referenced in the matched text are closed. This happens when the commit is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), or when a commit or merge request is merged into it. For example, if `Closes #4, #6, Related to #5` is included in a Merge Request -description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`. +description, issues `#4` and `#6` are closed automatically when the MR is merged, but not `#5`. Using `Related to` flags `#5` as a [related issue](related_issues.md), -but it will not close automatically. +but is not closed automatically.  @@ -219,9 +215,12 @@ If the issue is in a different repository than the MR, add the full URL for the Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> ``` +For performance reasons, automatic issue closing is disabled for the very first +push from an existing repository. + #### Default closing pattern -When not specified, the default issue closing pattern as shown below will be used: +When not specified, this default issue closing pattern is used: ```shell \b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) @@ -251,8 +250,8 @@ This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23. ``` -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, -as well as `#22` and `#23` in `group/otherproject`. `#17` won't be closed as it does +closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +as well as `#22` and `#23` in `group/otherproject`. `#17` is not closed as it does not match the pattern. It works with multi-line commit messages as well as one-liners when used from the command line with `git commit -m`. @@ -261,14 +260,14 @@ when used from the command line with `git commit -m`. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. The automatic issue closing feature can be disabled on a per-project basis -within the [project's repository settings](../settings/index.md). Referenced -issues will still be displayed as such but won't be closed automatically. +in the [project's repository settings](../settings/index.md). Referenced +issues are still displayed, but are not closed automatically.  This only applies to issues affected by new merge requests or commits. Already closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *within* the project and won't prevent other projects from closing it +requests *in* the project and does not prevent other projects from closing it via cross-project issues. #### Customizing the issue closing pattern **(CORE ONLY)** diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 2f8603e1db0..22dfd3a8719 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -57,7 +57,7 @@ and edit labels. ### Project labels -> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in 13.5. +> 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 @@ -228,7 +228,7 @@ to label notifications for the project only, or the whole group. > - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. Labels can have relative priorities, which are used in the **Label priority** and -**Priority** sort orders of the epic, issue, and merge request list pages. Prioritization +**Priority** sort orders of issues and merge request list pages. Prioritization for both group and project labels happens at the project level, and cannot be done from the group label list. @@ -241,7 +241,7 @@ means higher priority.  -On the epic, merge request, and issue list pages (for both groups and projects) you +On the merge request and issue list pages (for both groups and projects) you can sort by `Label priority` or `Priority`. If you sort by `Label priority`, GitLab uses this sort comparison order: diff --git a/doc/user/project/members/img/access_requests_management.png b/doc/user/project/members/img/access_requests_management.png Binary files differdeleted file mode 100644 index 9a1c9621e41..00000000000 --- a/doc/user/project/members/img/access_requests_management.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..950ef4dec01 --- /dev/null +++ b/doc/user/project/members/img/access_requests_management_13_8.png diff --git a/doc/user/project/members/img/add_user_email_accept.png b/doc/user/project/members/img/add_user_email_accept.png Binary files differdeleted file mode 100644 index cbee9e08c70..00000000000 --- a/doc/user/project/members/img/add_user_email_accept.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..ed980036af5 --- /dev/null +++ b/doc/user/project/members/img/add_user_email_accept_13_8.png diff --git a/doc/user/project/members/img/add_user_email_ready.png b/doc/user/project/members/img/add_user_email_ready.png Binary files differdeleted file mode 100644 index 0066eb3427b..00000000000 --- a/doc/user/project/members/img/add_user_email_ready.png +++ /dev/null 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_13_8.png Binary files differnew file mode 100644 index 00000000000..a610b46a176 --- /dev/null +++ b/doc/user/project/members/img/add_user_email_ready_13_8.png diff --git a/doc/user/project/members/img/add_user_email_search.png b/doc/user/project/members/img/add_user_email_search.png Binary files differdeleted file mode 100644 index 66bcd6aad80..00000000000 --- a/doc/user/project/members/img/add_user_email_search.png +++ /dev/null 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_13_8.png Binary files differnew file mode 100644 index 00000000000..934cf19bd3d --- /dev/null +++ b/doc/user/project/members/img/add_user_email_search_13_8.png diff --git a/doc/user/project/members/img/add_user_give_permissions.png b/doc/user/project/members/img/add_user_give_permissions.png Binary files differdeleted file mode 100644 index 376a3eefccc..00000000000 --- a/doc/user/project/members/img/add_user_give_permissions.png +++ /dev/null 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_13_8.png Binary files differnew file mode 100644 index 00000000000..1916d056a52 --- /dev/null +++ b/doc/user/project/members/img/add_user_give_permissions_13_8.png diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project.png b/doc/user/project/members/img/add_user_import_members_from_another_project.png Binary files differdeleted file mode 100644 index cb3b70bd4b5..00000000000 --- a/doc/user/project/members/img/add_user_import_members_from_another_project.png +++ /dev/null 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_13_8.png Binary files differnew file mode 100644 index 00000000000..a6dddec3fb7 --- /dev/null +++ b/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png diff --git a/doc/user/project/members/img/add_user_imported_members.png b/doc/user/project/members/img/add_user_imported_members.png Binary files differdeleted file mode 100644 index 51fd7688890..00000000000 --- a/doc/user/project/members/img/add_user_imported_members.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..725e447604f --- /dev/null +++ b/doc/user/project/members/img/add_user_imported_members_13_8.png diff --git a/doc/user/project/members/img/add_user_list_members.png b/doc/user/project/members/img/add_user_list_members.png Binary files differdeleted file mode 100644 index e0fa404288d..00000000000 --- a/doc/user/project/members/img/add_user_list_members.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..b8c0160c6d8 --- /dev/null +++ b/doc/user/project/members/img/add_user_list_members_13_8.png diff --git a/doc/user/project/members/img/add_user_search_people.png b/doc/user/project/members/img/add_user_search_people.png Binary files differdeleted file mode 100644 index 41767a9167c..00000000000 --- a/doc/user/project/members/img/add_user_search_people.png +++ /dev/null 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_13_8.png Binary files differnew file mode 100644 index 00000000000..e9aa58512ab --- /dev/null +++ b/doc/user/project/members/img/add_user_search_people_13_8.png diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png Binary files differdeleted file mode 100644 index e6e3f8f043b..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png Binary files differnew file mode 100644 index 00000000000..aa2aaf071e1 --- /dev/null +++ b/doc/user/project/members/img/other_group_sees_shared_project_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 differnew file mode 100644 index 00000000000..5d7948f0761 --- /dev/null +++ b/doc/user/project/members/img/project_groups_tab_13_8.png diff --git a/doc/user/project/members/img/project_members.png b/doc/user/project/members/img/project_members.png Binary files differdeleted file mode 100644 index 218f5a24d2e..00000000000 --- a/doc/user/project/members/img/project_members.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..9120d471b3b --- /dev/null +++ b/doc/user/project/members/img/project_members_13_8.png diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png Binary files differdeleted file mode 100644 index 7d83659ef7a..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..6cbbb386396 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png diff --git a/doc/user/project/members/img/share_project_with_groups_v13_6.png b/doc/user/project/members/img/share_project_with_groups_v13_6.png Binary files differdeleted file mode 100644 index 121e77671a3..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_v13_6.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 85cb139c45b..cccb998fc31 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -21,7 +21,7 @@ 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: @@ -46,17 +46,17 @@ using the dropdown on the right side: 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 +68,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 +83,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 +130,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. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index edfe8ae3b5b..d17717fb29c 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -26,19 +26,20 @@ 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. 1. Optionally, select an expiring date. 1. Click **Invite**. +1. After sharing 'Project Acme' with 'Engineering': + - The group is listed in the **Groups** tab. -  +  -1. After sharing 'Project Acme' with 'Engineering', the project is listed - on the group dashboard + - The project is listed on the group dashboard. -  +  Note that you can only share a project with: diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8eabef982c8..8adaae3b2ef 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -23,10 +23,10 @@ of the merge request. ## Enabling commit edits from upstream members -The feature can only be enabled by users who already have push access to the -source project and only lasts while the merge request is open. Once enabled, -upstream members will also be able to retry the pipelines and jobs of the -merge request: +From [GitLab 13.7 onwards](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: 1. While creating or editing a merge request, select the checkbox **Allow commits from members who can merge to the target branch**. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 04114968c80..6fa2340c7a4 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -60,7 +60,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). 1. Configure the default Browser Performance Testing CI job as follows in your `.gitlab-ci.yml` file: ```yaml diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 5a98338a81b..ca15ec154fc 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -72,10 +72,10 @@ It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are u 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). -First, you need GitLab Runner configured: +- 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. -- For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). -- With 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 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. Once you set up GitLab Runner, include the Code Quality template in your CI configuration: @@ -140,6 +140,99 @@ definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. +### Set up a private runner for code quality without Docker-in-Docker + +It's possible to configure your own runners and avoid Docker-in-Docker. You can use a +configuration that may greatly speed up job execution without requiring your runners +to operate in privileged mode. + +This alternative configuration uses socket binding to share the Runner's Docker daemon +with the job environment. Be aware that this configuration [has significant considerations](../../../ci/docker/using_docker_build.md#use-docker-socket-binding) +to be consider, but may be preferable depending on your use case. + +1. Register a new runner: + + ```shell + $ gitlab-runner register --executor "docker" \ + --docker-image="docker:stable" \ + --url "https://gitlab.com/" \ + --description "cq-sans-dind" \ + --tag-list "cq-sans-dind" \ + --locked="false" \ + --access-level="not_protected" \ + --docker-volumes "/cache"\ + --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ + --registration-token="<project_token>" \ + --non-interactive + ``` + +1. **Optional, but recommended:** Set the builds directory to `/tmp/builds`, + so job artifacts are periodically purged from the runner host. If you skip + this step, you must clean up the default builds directory (`/builds`) yourself. + You can do this by adding the following two flags to `gitlab-runner register` + in the previous step. + + ```shell + --builds-dir /tmp/builds + --docker-volumes /tmp/builds:/tmp/builds + ``` + + The resulting configuration: + + ```toml + [[runners]] + name = "cq-sans-dind" + url = "https://gitlab.com/" + token = "<project_token>" + executor = "docker" + builds_dir = "/tmp/builds" + [runners.docker] + tls_verify = false + image = "docker:stable" + privileged = false + disable_entrypoint_overwrite = false + oom_kill_disable = false + disable_cache = false + volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock", "/tmp/builds:/tmp/builds"] + shm_size = 0 + [runners.cache] + [runners.cache.s3] + [runners.cache.gcs] + ``` + +1. Apply two overrides to the `code_quality` job created by the template: + + ```yaml + include: + - template: Code-Quality.gitlab-ci.yml + + code_quality: + services: # Shut off Docker-in-Docker + tags: + - cq-sans-dind # Set this job to only run on our new specialized runner + ``` + +The end result is that: + +- Privileged mode is not used. +- Docker-in-Docker is not used. +- 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) +running Code Quality analysis ran significantly faster the second time: + + + +This configuration is not possible on `gitlab.com` shared runners. Shared runners +are configured with `privileged=true`, and they do not expose `docker.sock` into +the job container. As a result, socket binding cannot be used to make `docker` available +in the context of the job script. + +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. + ### Disabling the code quality job The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index cb95daa2cab..bc718ae867f 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -62,7 +62,7 @@ request's page at the top-right side: - 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. - Set the merge request as a [**Draft**](work_in_progress_merge_requests.md) to avoid accidental merges before it is ready. -Once you have created the merge request, you can also: +After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews). @@ -70,7 +70,7 @@ Once you have created the merge request, you can also: - Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). - Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews) in order to create multiple comments on a diff and publish them once you're ready. +- Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready. - Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). @@ -115,9 +115,10 @@ It is also possible to manage multiple assignees: > - [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.1. +> - [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)** WARNING: @@ -160,6 +161,53 @@ Feature.disable(:merge_request_reviewers) Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` +#### Reviewer approval rules + +> - [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-reviewer-approval-rules). **(CORE ONLY)** + +When editing the **Reviewers** field in a new or existing merge request, this feature +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 `Codeowner` without group detail. We intend to iterate on this feature in future releases. + +This example shows reviewers and approval rules when creating a new merge request: + + + +This example shows reviewers and approval rules in a merge request sidebar: + + + +##### Enable or disable Reviewer Approval Rules **(CORE ONLY)** + +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>)) +``` + ### Merge requests to close issues If the merge request is being created to resolve an issue, you can @@ -199,5 +247,5 @@ is set for deletion, the merge request widget displays the at once. By doing so, you save pipeline minutes. - Delete feature branches on merge or after merging them to keep your repository clean. - Take one thing at a time and ship the smallest changes possible. By doing so, - you'll have faster reviews and your changes will be less prone to errors. + reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. diff --git a/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png b/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png Binary files differnew file mode 100644 index 00000000000..2b31f3b42ee --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png Binary files differnew file mode 100644 index 00000000000..c2aa0689d65 --- /dev/null +++ b/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differnew file mode 100644 index 00000000000..3828868965b --- /dev/null +++ b/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 82b5d67ba2b..9154897d42d 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -103,7 +103,7 @@ job. An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the - [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). + [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). 1. Configure the default Load Performance Testing CI job in your `.gitlab-ci.yml` file. You need to include the template and configure it with variables: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 5c466654b31..93b85ce8669 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -8,7 +8,7 @@ type: reference, concepts # Squash and merge > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Core 11.0. +> - [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. With squash and merge you can combine all your merge request's commits into one and retain a clean history. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index c38b28f7718..3960f916f9b 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -33,7 +33,7 @@ This format was originally developed for Java, but most coverage analysis framew for other languages have plugins to add support for it, like: - [simplecov-cobertura](https://rubygems.org/gems/simplecov-cobertura) (Ruby) -- [gocover-cobertura](https://github.com/t-yuki/gocover-cobertura) (Golang) +- [gocover-cobertura](https://github.com/boumenot/gocover-cobertura) (Golang) Other coverage analysis frameworks support the format out of the box, for example: diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index fd7c58f12b9..4910751ece1 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -72,10 +72,26 @@ Let's consider the following scenario: ## Job token -A unique job token is generated for each job and provides the user read -access all projects that would be normally accessible to the user creating that -job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/groups/gitlab-org/-/epics/3559). +When a pipeline job is about to run, GitLab generates a unique token and injects it as the +[`CI_JOB_TOKEN` predefined variable](../../ci/variables/predefined_variables.md). +This token can authenticate [API requests](../../api/README.md) +from the job script (Runner) that needs to access the project's resources (for example, when +fetching a job artifact). + +Once the token is authenticated, GitLab identifies the user who triggered the job and uses this user +to authorize access to the resource. Therefore, this user must be assigned to +[a role that has the required privileges](../permissions.md). + +The job token has these limitations: + +- Not all APIs allow job tokens for authentication. See [this list](../../api/README.md#gitlab-ci-job-token) + for available endpoints. +- The token is valid only while the pipeline job runs. Once the job finishes, the token can't be + used for authentication. + +Although a job token is handy to quickly access a project's resources without any configuration, it +sometimes gives extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) +to redesign the feature for more strategic control of the access permissions. If you need your CI pipeline to push to the Package Registry, consider using [deploy tokens](deploy_tokens/index.md). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 4aa89ec6f8d..f02697a3cd5 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -24,7 +24,7 @@ GitLab Pages site. Note that **how to** add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are not an administrator of your domain, and don't have access to your registrar, -you'll need to ask for the technical support of your hosting service +you must ask the technical support of your hosting service to do it for you. To help you out, we've gathered some instructions on how to do that @@ -67,7 +67,7 @@ Example: - `www` => `CNAME` => `example.com` -This way, visitors visiting `www.example.com` will be redirected to +This way, visitors visiting `www.example.com` are redirected to `example.com`. ## MX record diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index f8173b4c004..8ed0ef82893 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -47,7 +47,8 @@ Click **Create New Domain**. #### 2. Get the verification code -Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step. +After you add a new domain to Pages, the verification code prompts you. Copy the values from GitLab +and paste them in your domain's control panel as a TXT record on the next step.  @@ -91,7 +92,7 @@ add a DNS apex `CNAME` record instead of an `A` record. The main advantage of doing so is that when GitLab Pages IP on GitLab.com changes for whatever reason, you don't need to update your `A` record. There may be a few exceptions, but **this method is not recommended** -as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. +as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. ##### For subdomains @@ -154,12 +155,11 @@ Once you have added all the DNS records:  -As soon as your domain becomes active, your website will be available -through your domain name. +As soon as your domain becomes active, your website is available through your domain name. WARNING: Considering GitLab instances with domain verification enabled, -if the domain cannot be verified for 7 days, it will be removed +if the domain can't be verified for 7 days, it's removed from the GitLab project. > **Notes:** @@ -169,9 +169,9 @@ from the GitLab project. to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). > - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification - will fail and attempts to visit your domain will respond with a 404. + fails, and attempts to visit your domain result in a 404. > - Once your domain has been verified, leave the verification record - in place: your domain will be periodically reverified, and may be + in place. Your domain is periodically reverified, and may be disabled if the record is removed. ##### Troubleshooting Pages domain verification @@ -211,7 +211,7 @@ For a subdomain: You can add more than one alias (custom domains and subdomains) to the same project. An alias can be understood as having many doors leading to the same room. -All the aliases you've set to your site will be listed on **Setting > Pages**. +All the aliases you've set to your site are listed on **Setting > Pages**. From that page, you can view, add, and remove them. ### Redirecting `www.domain.com` to `domain.com` with Cloudflare @@ -294,7 +294,7 @@ Sublime Text, Atom, Dreamweaver, Brackets, etc). To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your -website via HTTP will be automatically redirected to HTTPS via 301. +website through HTTP are automatically redirected to HTTPS through 301. It works with both the GitLab default domain and with your custom domain (as long as you've set a valid certificate for it). 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 3dea35153e4..aa06a15a8c0 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 @@ -50,15 +50,15 @@ Once you've met the requirements, enable Let's Encrypt integration: 1. Click **Save changes**. -Once enabled, GitLab will obtain a LE certificate and add it to the -associated Pages domain. It also will be renewed automatically by GitLab. +Once enabled, GitLab obtains a LE certificate and add it to the +associated Pages domain. GitLab also renews it automatically. > **Notes:** > > - Issuing the certificate and updating Pages configuration > **can take up to an hour**. -> - If you already have SSL certificate in domain settings it -> will continue to work until it will be replaced by Let's Encrypt's certificate. +> - If you already have an SSL certificate in domain settings it +> continues to work until replaced by the Let's Encrypt's certificate. ## Troubleshooting 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 dc73a664324..e8c6305dbab 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 @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w _Read this document for a brief overview of SSL/TLS certificates in the scope of GitLab Pages, for beginners in web development._ -Every GitLab Pages project on GitLab.com will be available under +Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set up your Pages project with your custom (sub)domain, if you want -it secured by HTTPS, you will have to issue a certificate for that +it secured by HTTPS, you must issue a certificate for that (sub)domain and install it on your project. NOTE: @@ -41,9 +41,6 @@ the connection between the **client** (you, me, your visitors) and the **server** (where you site lives), through a keychain of authentications and validations. -How about taking Josh's advice and protecting our sites too? We will be -well supported, and we'll contribute to a safer internet. - ## Organizations supporting HTTPS There is a huge movement in favor of securing all the web. W3C fully @@ -62,8 +59,8 @@ GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digice for public websites for security reasons and to ensure that browsers trust your site's certificate. There are various kinds of certificates, each one -with a certain security level. A static personal website will -not require the same security level as an online banking web app, +with a certain security level. A static personal website doesn't +require the same security level as an online banking web app, for instance. There are some certificate authorities that diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 6dd431e02b0..e0d5e8be535 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -41,7 +41,7 @@ configuration for the Pages site to generate properly. If everything is configured correctly, the site can take approximately 30 minutes to deploy. -You can watch the pipeline run by going to **CI / CD > Pipelines**. +You can watch the pipeline run by navigating to **CI / CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 525bbde4671..c7916b7c01e 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 @@ -17,7 +17,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: -1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. +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. 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**. @@ -50,7 +50,7 @@ You can take some **optional** further steps: If you set the repository path to `gitlab-tests.gitlab.io`, the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. -  +  - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) 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/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 230e88f35f5..3f2df634e3a 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a GitLab Pages website from scratch -This tutorial shows you how to create a Pages site from scratch. You will start with +This tutorial shows you how to create a Pages site from scratch. You start with a blank project and create your own CI file, which gives instruction to a [runner](https://docs.gitlab.com/runner/). When your CI/CD [pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. @@ -218,7 +218,7 @@ There are three default stages for GitLab CI/CD: build, test, and deploy. If you want to test your script and check the built site before deploying -to production, you can run the test exactly as it will run when you +to production, you can run the test exactly as it runs when you push to `master`. To specify a stage for your job to run in, @@ -376,7 +376,7 @@ test: In this case, you need to exclude the `/vendor` directory from the list of folders Jekyll builds. Otherwise, Jekyll -will try to build the directory contents along with the site. +tries to build the directory contents along with the site. In the root directory, create a file called `_config.yml` and add this content: diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index f549c4e6e7d..801fe0c7ef0 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -16,7 +16,7 @@ wildcard domain with your sysadmin. This guide is valid for any GitLab instance, replace the Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. If you set up a GitLab Pages project on GitLab, -it will automatically be accessible under a +it's automatically accessible under a subdomain of `namespace.example.io`. The [`namespace`](../../group/index.md#namespaces) is defined by your username on GitLab.com, @@ -45,35 +45,35 @@ To understand Pages domains clearly, read the examples below. - You created a project called `blog` under your username `john`, therefore your project URL is `https://gitlab.com/john/blog/`. Once you enable GitLab Pages for this project, and build your site, - it will be available under `https://john.gitlab.io/blog/`. + you can access it at `https://john.gitlab.io/blog/`. - You created a group for all your websites called `websites`, and a project within this group is called `blog`. Your project URL is `https://gitlab.com/websites/blog/`. Once you enable - GitLab Pages for this project, the site will live under + GitLab Pages for this project, the site is available at `https://websites.gitlab.io/blog/`. - You created a group for your engineering department called `engineering`, a subgroup for all your documentation websites called `docs`, and a project within this subgroup is called `workflows`. Your project URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable - GitLab Pages for this project, the site will live under + GitLab Pages for this project, the site is available at `https://engineering.gitlab.io/docs/workflows`. ### User and Group website examples - Under your username, `john`, you created a project called - `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. + `john.gitlab.io`. Your project URL is `https://gitlab.com/john/john.gitlab.io`. Once you enable GitLab Pages for your project, your website - will be published under `https://john.gitlab.io`. + is published under `https://john.gitlab.io`. - Under your group `websites`, you created a project called - `websites.gitlab.io`. your project's URL will be `https://gitlab.com/websites/websites.gitlab.io`. + `websites.gitlab.io`. Your project's URL is `https://gitlab.com/websites/websites.gitlab.io`. Once you enable GitLab Pages for your project, - your website will be published under `https://websites.gitlab.io`. + your website is published under `https://websites.gitlab.io`. **General example:** -- On GitLab.com, a project site will always be available under +- On GitLab.com, a project site is always available under `https://namespace.gitlab.io/project-name` -- On GitLab.com, a user or group website will be available under +- On GitLab.com, a user or group website is available under `https://namespace.gitlab.io/` - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. @@ -87,7 +87,7 @@ Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, whenever you publish a project website (`namespace.gitlab.io/project-name`), -you'll have to look for this configuration (base URL) on your SSG's +you must look for this configuration (base URL) on your SSG's documentation and set it up to reflect this pattern. For example, for a Jekyll site, the `baseurl` is defined in the Jekyll @@ -99,11 +99,11 @@ baseurl: "/blog" ``` On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the `baseurl` will -already be configured this way, as all examples there are project -websites. If you decide to make yours a user or group website, you'll -have to remove this configuration from your project. For the Jekyll -example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: +our [default examples](https://gitlab.com/pages), the `baseurl` is +already configured this way, as all examples there are project +websites. If you decide to make yours a user or group website, you +must remove this configuration from your project. For the Jekyll +example we just mentioned, you must change Jekyll's `_config.yml` to: ```yaml baseurl: "" diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 846d30e898c..c9e28bf15c2 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -81,10 +81,12 @@ becomes available automatically. To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/README.md) to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named -`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. +`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md). +A specific `job` called `pages` in the configuration file makes GitLab aware that you're deploying a +GitLab Pages website. You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), -`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll +`*.gitlab.io`, or your own domain (`example.com`). In that case, you need administrator access to your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -94,15 +96,15 @@ The following diagrams show the workflows you might follow to get started with P ## Access to your Pages site If you're using GitLab Pages default domain (`.gitlab.io`), -your website will be automatically secure and available under +your website is automatically secure and available under HTTPS. If you're using your own custom domain, you can optionally secure it with SSL/TLS certificates. -If you're using GitLab.com, your website will be publicly available to the internet. +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), -your websites will be published on your own server, according to the +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 5a284bf57c3..8380f367212 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -44,19 +44,19 @@ Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete l You can provide your own 403 and 404 error pages by creating the `403.html` and `404.html` files respectively in the root directory of the `public/` directory -that will be included in the artifacts. Usually this is the root directory of +that are included in the artifacts. Usually this is the root directory of your project, but that may differ depending on your static generator configuration. If the case of `404.html`, there are different scenarios. For example: - If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/existing_file`, GitLab Pages will try to serve first + `/projectname/non/existing_file`, GitLab Pages tries to serve first `/projectname/404.html`, and then `/404.html`. - If you use user/group Pages (served under `/`) and try to access - `/non/existing_file` GitLab Pages will try to serve `/404.html`. + `/non/existing_file` GitLab Pages tries to serve `/404.html`. - If you use a custom domain and try to access `/non/existing_file`, GitLab - Pages will try to serve only `/404.html`. + Pages tries to serve only `/404.html`. ## Redirects in GitLab Pages @@ -71,8 +71,8 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you ever feel the need to purge your Pages content, you can do so by going to your project's settings through the gear icon in the top right, and then -navigating to **Pages**. Hit the **Remove pages** button and your Pages website -will be deleted. +navigating to **Pages**. Click the **Remove pages** button to delete your Pages +website.  @@ -81,9 +81,9 @@ will be deleted. When using Pages under the general domain of a GitLab instance (`*.example.io`), you _cannot_ use HTTPS with sub-subdomains. That means that if your username or group name contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` will _not_ work. This is a limitation of the -[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages will continue to work provided you -don't redirect HTTP to HTTPS. +`https://foo.bar.example.io` does _not_ work. This is a limitation of the +[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). +HTTP pages continue to work provided you don't redirect HTTP to HTTPS. GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). You can only create the highest-level group website. @@ -130,11 +130,11 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic), -whenever a new commit is pushed to a branch that will be used specifically for -your pages. +whenever a new commit is pushed to a branch used specifically for your +pages. That way, you can have your project's code in the `master` branch and use an -orphan branch (let's name it `pages`) that will host your static generator site. +orphan branch (let's name it `pages`) to host your static generator site. You can create a new empty branch like this: @@ -142,9 +142,9 @@ You can create a new empty branch like this: git checkout --orphan pages ``` -The first commit made on this new branch will have no parents and it will be -the root of a new history totally disconnected from all the other branches and -commits. Push the source files of your static generator in the `pages` branch. +The first commit made on this new branch has no parents and is the root of a +new history totally disconnected from all the other branches and commits. +Push the source files of your static generator in the `pages` branch. Below is a copy of `.gitlab-ci.yml` where the most significant line is the last one, specifying to execute everything in the `pages` branch: @@ -172,9 +172,9 @@ also includes `.gitlab-ci.yml`. Most modern browsers support downloading files in a compressed format. This speeds up downloads by reducing the size of files. -Before serving an uncompressed file, Pages will check whether the same file -exists with a `.br` or `.gz` extension. If it does, and the browser supports receiving -compressed files, it will serve that version instead of the uncompressed one. +Before serving an uncompressed file, Pages checks if the same file exists with +a `.br` or `.gz` extension. If it does, and the browser supports receiving +compressed files, it serves that version instead of the uncompressed one. To take advantage of this feature, the artifact you upload to the Pages should have this structure: @@ -236,10 +236,10 @@ public/ ``` Pages supports reaching each of these files through several different URLs. In -particular, it will always look for an `index.html` file if the URL only +particular, it always looks for an `index.html` file if the URL only specifies the directory. If the URL references a file that doesn't exist, but -adding `.html` to the URL leads to a file that *does* exist, it will be served -instead. Here are some examples of what will happen given the above Pages site: +adding `.html` to the URL leads to a file that *does* exist, it's served +instead. Here are some examples of what happens given the above Pages site: | URL path | HTTP response | File served | | -------------------- | ------------- | ----------- | @@ -275,7 +275,7 @@ to private, internal or public. ### Do I need to create a user/group website before creating a project website? -No, you don't. You can create your project first and it will be accessed under +No, you don't. You can create your project first and access it under `http(s)://namespace.example.io/projectname`. ## Known issues diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index f2b75354bf8..b5932fc8766 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -61,7 +61,7 @@ might be slightly different. Follow the ``` Alternatively, you can register without adding an e-mail account, - but you won't be notified about the certificate expiration's date: + but you aren't notified about the certificate expiration's date: ```shell sudo certbot certonly -a manual -d example.com --register-unsafely-without-email @@ -71,10 +71,10 @@ might be slightly different. Follow the Read through CertBot's documentation on their [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). -1. You'll be prompted with a message to agree with their terms. +1. You're prompted with a message to agree with their terms. Press `A` to agree and `Y` to let they log your IP. - CertBot will then prompt you with the following message: + CertBot then prompts you with the following message: ```shell Create a file containing just this data: @@ -88,7 +88,7 @@ might be slightly different. Follow the Press Enter to Continue ``` -1. **Do not press Enter yet.** Let's Encrypt will need to verify your +1. **Do not press Enter yet.** Let's Encrypt needs to verify your domain ownership before issuing the certificate. To do so, create 3 consecutive directories under your website's root: `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` @@ -103,11 +103,11 @@ might be slightly different. Follow the `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` to allow Let's Encrypt to verify the ownership of your domain, therefore, it needs to be part of the website content under the - repo's [`public`](index.md#how-it-works) folder. + repository's [`public`](index.md#how-it-works) folder. 1. Add, commit, and push the file into your repository in GitLab. Once the pipeline passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot will then prompt you with the following message: + certificate. CertBot then prompts you with the following message: ```shell Waiting for verification... @@ -157,7 +157,7 @@ valid certificates)**. ## Renewal -Let's Encrypt certificates expire every 90 days and you'll have to +Let's Encrypt certificates expire every 90 days and you must renew them periodically. To renew all your certificates at once, run: ```shell diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 9d17277fe9e..a2a17a4f2ca 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -28,20 +28,20 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v with GitLab Pages, depending on your project's visibility: - If your project is private: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. - If your project is internal: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone with access**: Everyone logged into GitLab is able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. - If your project is public: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **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**. The next time someone tries to access your website and the access control is -enabled, they will be presented with a page to sign into GitLab and verify they +enabled, they're presented with a page to sign into GitLab and verify they can access the website. ## Terminating a Pages session diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 9f849051f40..64be3182dab 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -9,8 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672): > once an action is executed, an alert appears when a quick action is successfully applied. -> - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/16877) and later, you can use +> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/16877): you can use > quick actions when updating the description of issues, epics, and merge requests. +> - Introduced in [GitLab 13.8](https://gitlab.com/gitlab-org/gitlab/-/issues/292393): when you enter +> `/` into a description or comment field, all available quick actions are displayed in a scrollable list. +> - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. Quick actions are textual shortcuts for common actions on issues, epics, merge requests, and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. @@ -31,6 +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. | | `/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)** | @@ -56,6 +62,8 @@ 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. | +| `/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)** | | `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<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)** | @@ -78,7 +86,9 @@ The following quick actions are applicable to descriptions, discussions and thre | `/title <new title>` | ✓ | ✓ | ✓ | Change title. | | `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | -| `/unassign` | ✓ | ✓ | | Remove all assignees. | +| `/unassign` | | ✓ | | Remove all assignees. | +| `/unassign_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | +| `/unassign_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/index.md b/doc/user/project/releases/index.md index 7b412270938..90d7ac0a3c2 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -200,7 +200,7 @@ If the job that's executing is within a freeze period, GitLab CI/CD creates an e variable named `$CI_DEPLOY_FREEZE`. To prevent the deployment job from executing, create a `rules` entry in your -`gitlab-ci.yaml`, for example: +`gitlab-ci.yml`, for example: ```yaml deploy_to_production: @@ -274,14 +274,11 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m ### Release assets -You can currently add the following types of assets to each release: +You can add the following types of assets to each release: - [Source code](#source-code) - [Links](#links) -GitLab will support more asset types in the future, including objects such -as pre-built packages, compliance/security evidence, or container images. - #### Permanent links to release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. @@ -336,8 +333,8 @@ The four types of links are "Runbook," "Package," "Image," and "Other." > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. -This data is saved in a JSON file and called *release evidence*. The feature currently -includes test artifacts and linked milestones (and will include issues) to facilitate +This data is saved in a JSON file and called *release evidence*. The feature +includes test artifacts and linked milestones to facilitate internal processes, like external audits. To access the release evidence, on the Releases page, click the link to the JSON file that's listed diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 75e1aea632f..f7da3629c23 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -34,10 +34,6 @@ Forking a project is, in most cases, a two-step process. The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. WARNING: -In GitLab 12.6 and later, when project owners [reduce a project's visibility](../../../public_access/public_access.md#reducing-visibility), -it **removes the relationship** between a project and all its forks. - -WARNING: When a public project with the repository feature set to "Members only" is forked, the repository will be public in the fork. The owner of the fork will need to manually change the visibility. This is being diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index e1d84baec4d..c4f5d330f63 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -31,7 +31,7 @@ that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), -you'll see on the repository's file tree an icon next to the file name +you'll see on the repository's file tree an icon next to the filename according to its extension:  @@ -236,18 +236,24 @@ lock your files to prevent any conflicting changes. You can access your repositories via [repository API](../../../api/repositories.md). -## Clone in Apple Xcode +## Clone a repository -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0 +Learn how to [clone a repository through the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). + +Alternatively, clone directly into a code editor as documented below. + +### Clone to 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 -in Xcode using the new **Open in Xcode** button, located next to the Git URL +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. ## Download Source Code -> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. -> Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. +> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. +> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. The source code stored in a repository can be downloaded from the UI. By clicking the download icon, a dropdown will open with links to download the following: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 96694a9e954..4a7f75ba1ac 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -8,19 +8,16 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring Repository mirroring allows for mirroring of repositories to and from external sources. It can be -used to mirror branches, tags, and commits between repositories. +used to mirror branches, tags, and commits between repositories. It is useful when you want to use +a repository outside of GitLab. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update at most once every 5 minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). -## Overview - -Repository mirroring is useful when you want to use a repository outside of GitLab. - There are two kinds of repository mirroring supported by GitLab: -- Push: for mirroring a GitLab repository to another location. -- Pull: for mirroring a repository from another location to GitLab. **(STARTER)** +- [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)** When the mirror repository is updated, all new branches, tags, and commits will be visible in the project's activity feed. @@ -31,8 +28,7 @@ immediate update, unless: - The mirror is already being updated. - The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. -For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), -the URL to the original repository is only displayed to users with +For security reasons, the URL to the original repository is only displayed to users with Maintainer or Owner permissions to the mirrored project. ## Use cases @@ -62,7 +58,8 @@ For an existing project, you can set up push mirroring as follows: 1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. 1. Enter a repository URL. 1. Select **Push** from the **Mirror direction** dropdown. -1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. Select an authentication method from the **Authentication method** dropdown. + You can authenticate with either a password or an [SSH key](#ssh-authentication). 1. Check the **Only mirror protected branches** box, if necessary. 1. Check the **Keep divergent refs** box, if desired. 1. Click the **Mirror repository** button to save the configuration. @@ -88,17 +85,7 @@ section. You can also create and modify project push mirrors through the [remote mirrors API](../../../api/remote_mirrors.md). -### Push only protected branches **(CORE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. -> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. - -You can choose to only push your protected branches from GitLab to your remote repository. - -To use this option, check the **Only mirror protected branches** box when creating a repository -mirror. - -### Keep divergent refs **(CORE)** +### Keep divergent refs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. @@ -119,7 +106,7 @@ update. NOTE: After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). -## Setting up a push mirror from GitLab to GitHub **(CORE)** +### Setting up a push mirror from GitLab to GitHub To set up a mirror from GitLab to GitHub, you need to follow these steps: @@ -132,7 +119,7 @@ The mirrored repository will be listed. For example, `https://*****:*****@github The repository will push soon. To force a push, click the **Update now** (**{retry}**) button. -## Setting up a push mirror from GitLab to AWS CodeCommit +### Setting up a push mirror from GitLab to AWS CodeCommit AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. @@ -210,7 +197,7 @@ To test mirroring by forcing a push, click the half-circle arrows button (hover If **Last successful update** shows a date, you have configured mirroring correctly. If it is not working correctly a red `error` tag appears and shows the error message as hover text. -## Setting up a push mirror to another GitLab instance with 2FA activated +### Setting up a push mirror to another GitLab instance with 2FA activated 1. On the destination GitLab instance, create a [personal access token](../../profile/personal_access_tokens.md) with `write_repository` scope. 1. On the source GitLab instance: @@ -249,8 +236,8 @@ To configure mirror pulling for an existing project:  Because GitLab is now set to pull changes from the upstream repository, you should not push commits -directly to the repository on GitLab. Instead, any commits should be pushed to the upstream repository. -Changes pushed to the upstream repository will be pulled into the GitLab repository, either: +directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. +Changes pushed to the remote repository will be pulled into the GitLab repository, either: - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. @@ -275,10 +262,62 @@ 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. -### SSH authentication +### Overwrite diverged branches **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. + +You can choose to always update your local branches with remote versions, even if they have +diverged from the remote. + +WARNING: +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)** + +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 +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)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. + +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: + +- Project's main dashboard. +- Pull mirror settings page. + +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)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. + +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), +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)** + +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. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 +## 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. SSH authentication is mutual: @@ -367,50 +406,6 @@ NOTE: The generated keys are stored in the GitLab database, not in the filesystem. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. -### Overwrite diverged branches **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. - -You can choose to always update your local branches with remote versions, even if they have -diverged from the remote. - -WARNING: -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. - -### Only mirror protected branches **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3326) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. - -You can choose to pull mirror only the protected branches from your remote repository to GitLab. -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. - -### Hard failure **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. - -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: - -- Project's main dashboard. -- Pull mirror settings page. - -When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the -project mirroring again by [Forcing an update](#forcing-an-update). - -### Trigger update using API **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. - -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), -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). - ## Forcing an update **(CORE)** While mirrors are scheduled to update automatically, you can always force an update by using the @@ -429,10 +424,7 @@ bidirectional mirroring, you should prepare for the likely conflicts by deciding them and how they will be resolved. Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can -be prevented by: - -- [Pulling only protected branches](#only-mirror-protected-branches). -- [Pushing only protected branches](#push-only-protected-branches). +be prevented by [mirroring only protected branches](#mirror-only-protected-branches). You should [protect the branches](../protected_branches.md) you wish to mirror on both remotes to prevent conflicts caused by rewriting history. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 24bfeee5e7f..b9477da3937 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -19,7 +19,7 @@ From a project's files page, click the '+' button to the right of the branch sel Choose **New file** from the dropdown.  -Enter a file name in the **Filename** box. Then, add file content in the editor +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 diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 9d75c4ab071..c99b0d91523 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -34,7 +34,7 @@ Users with Reporter or higher [permissions](../../permissions.md) can create req To create a requirement: -1. From your project page, go to **Requirements**. +1. In a project, go to **Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -200,10 +200,10 @@ requirements_confirmation: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. -You can import requirements to a project by uploading a CSV file with the columns -`title` and `description`. +You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) +with the columns `title` and `description`. -The user uploading the CSV file will be set as the author of the imported requirements. +After the import, the user uploading the CSV file is set as the author of the imported requirements. Users with Reporter or higher [permissions](../../permissions.md) can import requirements. @@ -213,20 +213,20 @@ Before you import your file: - Consider importing a test file containing only a few requirements. There is no way to undo a large import without using the GitLab API. -- Ensure your CSV file meets the [file format](#csv-file-format) requirements. +- Ensure your CSV file meets the [file format](#imported-csv-file-format) requirements. To import requirements: -1. Navigate to a project's Requirements page. - - If the project already has existing requirements, click the import icon (**{import}**) at the +1. In a project, go to **Requirements**. + - If the project already has existing requirements, select the import icon (**{import}**) in the top right. - - For a project without any requirements, click **Import CSV** in the middle of the page. -1. Select the file and click **Import requirements**. + - For a project without any requirements, select **Import CSV** in the middle of the page. +1. Select the file and select **Import requirements**. The file is processed in the background and a notification email is sent to you after the import is complete. -### CSV file format +### Imported CSV file format When importing requirements from a CSV file, it must be formatted in a certain way: @@ -257,3 +257,37 @@ Another Title,"A description, with a comma" The limit depends on the configuration value of Max Attachment Size for the GitLab instance. 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. + +You can export GitLab requirements to a +[CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification +email as an attachment. + +By exporting requirements, you and your team can import them into another tool or share them with +your customers. Exporting requirements can aid collaboration with higher-level systems, as well as +audit and regulatory compliance tasks. + +Users with Reporter or higher [permissions](../../permissions.md) can export requirements. + +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. Select **Export requirements**. The exported CSV file is sent to the email address associated with your user. + +### Exported CSV file format + +You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, +OpenOffice Calc, or Google Sheets. + +The exported CSV file contains the following columns: + +- Requirement ID +- Title +- Description +- Author Username +- Latest Test Report State +- Latest Test Report Created At (UTC) diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 4f3ca12c582..76156690fe7 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -10,32 +10,38 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. -Service Desk is a module that allows your team to connect directly -with any external party through email right inside of GitLab; no external tools required. -An ongoing conversation right where your software is built ensures that user feedback ends -up directly where it's needed, helping you build the right features to solve your users' -real problems. +Service Desk is a module that allows your team to connect +with any external party through email, without any external tools. +An ongoing conversation in the same place as where your software +is built ensures user feedback ends up where it's needed. -With Service Desk, you can provide efficient email support to your customers, who can now -email you bug reports, feature requests, or general feedback that will all end up in your -GitLab project as new issues. In turn, your team can respond straight from the project. +With Service Desk, you can provide efficient email support to your customers. They can +email you bug reports, feature requests, or general feedback. They all end up in your +GitLab project as new issues. In turn, your team can respond directly from the project. As Service Desk is built right into GitLab itself, the complexity and inefficiencies -of multiple tools and external integrations are eliminated, significantly shortening +of multiple tools and external integrations are eliminated. This significantly shortens the cycle time from feedback to software update. For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/blog/2017/05/09/demo-service-desk/). -## Use cases +## How it works + +GitLab Service Desk enables people to create issues in your +GitLab instance without needing their own user account. + +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. The codebase is hosted in your GitLab instance, built and deployed with GitLab CI/CD. -Here's how Service Desk will work for you: +Here's how Service Desk works for you: 1. You provide a project-specific email address to your paying customers, who can email you directly - from within the app. + from the application. 1. Each email they send creates an issue in the appropriate project. 1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues. @@ -43,61 +49,54 @@ Here's how Service Desk will work for you: 1. Your team starts working on implementing code to solve your customer's problem. 1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically. -1. The customer will have been attended successfully via email, without having real access to your +1. The customer's requests are handled through email, without ever having access to your GitLab instance. 1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer. -## How it works - -GitLab Service Desk is a simple way to allow people to create issues in your -GitLab instance without needing their own user account. - -It provides a unique email address for end users to create issues in a project, -and replies can be sent either through the GitLab interface or by email. End -users will only see the thread through email. - ## 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. -If you have project maintainer access you have the option to set up Service Desk. -Follow these steps to do so: +If you have project maintainer access you have the option to set up Service Desk. Follow these steps: 1. [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). + 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. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. These issues will be [confidential](issues/confidential_issues.md), so they will - only be visible to project members. Note that in GitLab 11.7, we updated the generated email + 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. WARNING: - This email address can be used by anyone to create an issue on this project, whether or not they - have access to your GitLab instance. We recommend **putting this behind an alias** so it can be - changed if needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab + 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. 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. -  - -Service Desk is now enabled for this project! You should be able to access it from your project -navigation's **Issues** menu. +Service Desk is now enabled for this project! You should be able to access it from your project's +**Issues** menu.  ### Using customized email templates - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - [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. + +An email is sent to the author when: -When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. +- 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/` @@ -106,39 +105,46 @@ directory in your repository. Commit and push to your default branch. #### Thank you email The **Thank you email** is the email sent to a user after they submit an issue. -The file name of the template has to be `thank_you.md`. -You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID in the email and -`%{ISSUE_PATH}` placeholder which will be replaced by project path and the issue IID. +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: + +- `%{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. #### New note email -The **New note email** is the email sent to a user when the issue they submitted has a new comment. -The file name of the template has to be `new_note.md`. -You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID -in the email, `%{ISSUE_PATH}` placeholder which will be replaced by - project path and the issue IID and `%{NOTE_TEXT}` placeholder which will be replaced by the note text. +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: + +- `%{ISSUE_ID}`: issue IID +- `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{NOTE_TEXT}`: note text ### Using custom email display name > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. -You can customize the email display name. Emails sent from Service Desk will have +You can customize the email display name. Emails sent from Service Desk have this name in the `From` header. The default display name is `GitLab Support Bot`. -### Using custom email address **(CORE ONLY)** +To edit the custom email display name: + +1. In a project, go to **Settings > General > Service Desk**. +1. Enter a new name in **Email display name**. +1. Select **Save Changes**. + +### Using custom email address > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. -> - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) on GitLab 13.7. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-custom-email-address). **(CORE ONLY)** - -If the `service_desk_email` feature flag is enabled in your configuration, -then it's possible to create Service Desk issues by sending emails to the -custom Service Desk email address, which should have the following format: +> - [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 +issues by sending emails to the Service Desk email address. The default +address has the following format: `project_contact+%{key}@example.com`. The `%{key}` part is used to find the project where the issue should be created. The @@ -148,53 +154,57 @@ The `%{key}` part is used to find the project where the issue should be created. You can set the project name suffix in your project's Service Desk settings. It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). - +NOTE: +The `service_desk_email` and `incoming_email` configurations should +always use separate mailboxes. This is important, because emails picked from +`service_desk_email` mailbox are processed by a different worker and it would +not recognize `incoming_email` emails. -You can add the following snippets to your configuration. +To configure a custom email address for Service Desk, add the following snippets to your configuration file: -Example for installations from source: +- Example for installations from source: -```yaml -service_desk_email: - enabled: true - address: "project_contact+%{key}@example.com" - user: "project_support@example.com" - password: "[REDACTED]" - host: "imap.gmail.com" - port: 993 - ssl: true - start_tls: false - log_path: "log/mailroom.log" - mailbox: "inbox" - idle_timeout: 60 - expunge_deleted: true -``` + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_support@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true + ``` -Example for Omnibus GitLab installations: +- Example for Omnibus GitLab installations: -```ruby -gitlab_rails['service_desk_email_enabled'] = true + ```ruby + gitlab_rails['service_desk_email_enabled'] = true -gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" -gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" + gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" -gitlab_rails['service_desk_email_password'] = "[REDACTED]" + gitlab_rails['service_desk_email_password'] = "[REDACTED]" -gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" -gitlab_rails['service_desk_email_idle_timeout'] = 60 + gitlab_rails['service_desk_email_idle_timeout'] = 60 -gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" -gitlab_rails['service_desk_email_host'] = "imap.gmail.com" + gitlab_rails['service_desk_email_host'] = "imap.gmail.com" -gitlab_rails['service_desk_email_port'] = 993 + gitlab_rails['service_desk_email_port'] = 993 -gitlab_rails['service_desk_email_ssl'] = true + gitlab_rails['service_desk_email_ssl'] = true -gitlab_rails['service_desk_email_start_tls'] = false -``` + gitlab_rails['service_desk_email_start_tls'] = false + ``` In this case, suppose the `mygroup/myproject` project Service Desk settings has the project name suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. @@ -203,27 +213,10 @@ As a result, a new Service Desk issue is created from this email in the `mygroup The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). -#### Disable custom email address **(CORE ONLY)** - -Service Desk custom email 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(:service_desk_custom_address) -``` - -To disable it: - -```ruby -Feature.disable(:service_desk_custom_address) -``` - ## Using Service Desk +There are a few ways Service Desk can be used. + ### As an end user (issue creator) To create a Service Desk issue, an end user does not need to know anything about @@ -235,29 +228,30 @@ receive an email back confirming receipt: This also gives the end user an option to unsubscribe. If they don't choose to unsubscribe, then any new comments added to the issue -will be sent as emails: +are sent as emails:  -And any responses they send will be displayed in the issue itself. +Any responses they send via email are displayed in the issue itself. ### As a responder to the issue -For responders to the issue, everything works as usual. They will see a familiar looking -issue tracker, where they can see issues created via customer support requests and -filter and interact with them just like other GitLab issues. +For responders to the issue, everything works just like other GitLab issues. +GitLab displays a familiar-looking issue tracker where responders can see +issues created through customer support requests, and filter or interact with them.  -Messages from the end user will show as coming from the special Support Bot user, but apart from that, -you can read and write comments as you normally do: +Messages from the end user are shown as coming from the special +[Support Bot user](../../subscriptions/self_managed/index.md#billable-users). +You can read and write comments as you normally do in GitLab:  Note that: - The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, will be shown on emails. +- The path to the project, including its group or namespace, are shown in emails. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 53233cc347e..27727890383 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -179,7 +179,7 @@ If use of the `Internal` visibility level all imported projects are given the visibility of `Private`. NOTE: -The maximum import file size can be set by the Administrator, default is 50MB. +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). ### Project import status diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 41f404de4f2..26ef5e2260a 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -52,10 +52,6 @@ If you set **Project Visibility** to public, you can limit access to some featur to **Only Project Members**. In addition, you can select the option to [Allow users to request access](../members/index.md#project-membership-and-requesting-access). -WARNING: -If you [reduce a project's visibility level](../../../public_access/public_access.md#reducing-visibility), -that action unlinks all forks of that project. - Use the switches to enable or disable the following features: | Option | More access limit options | Description | diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 494f0b725e3..39de9ab9ca2 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -38,8 +38,10 @@ For examples of how you can use a project access token to authenticate with the ## Project bot users -For each project access token created, a bot user will also be created and added to the project with -["Maintainer" level permissions](../../permissions.md#project-members-permissions). +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. + +For each project access token created, a bot user is created and added to the project with +[Maintainer level permissions](../../permissions.md#project-members-permissions). For the bot: @@ -49,15 +51,15 @@ For the bot: API calls made with a project access token are associated with the corresponding bot user. -These users will appear in **Members** but can not be modified. -Furthermore, the bot user can not be added to any other project. +These bot users are included in a project's **Members** list but cannot be modified. Also, a bot +user cannot be added to any other project. - The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. - The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. -When the project access token is [revoked](#revoking-a-project-access-token) the bot user is then deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). - -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. +When the project access token is [revoked](#revoking-a-project-access-token) the bot user is deleted +and all records are moved to a system-wide user with the username "Ghost User". For more +information, see [Associated Records](../../profile/account/delete_account.md#associated-records). ## Revoking a project access token @@ -72,7 +74,7 @@ the following table. | Scope | Description | | ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API, including the Package Registry](../../packages/package_registry/index.md). | +| `api` | Grants complete read/write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 29b24028e48..af8e78afb28 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -33,8 +33,8 @@ start seeing results. ## Command palette You can see all available commands for manipulating editor content by pressing -the <kbd>F1</kbd> key when the editor is in focus. After that, -you'll see a complete list of available commands for +the <kbd>F1</kbd> key when the editor is in focus. After that, the editor displays +a complete list of available commands for manipulating editor content. The editor supports commands for multi-cursor editing, code block folding, commenting, searching and replacing, navigating editor warnings and suggestions, and more. @@ -47,7 +47,7 @@ the command without having to select it in the command palette. ## Syntax highlighting -As expected from an IDE, syntax highlighting for many languages within +As expected from an IDE, syntax highlighting for many languages in the Web IDE makes your direct editing even easier. The Web IDE currently provides: @@ -78,7 +78,7 @@ All the themes GitLab supports for syntax highlighting are added to the Web IDE' You can pick a theme from your [profile preferences](../../profile/preferences.md). The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), +the [Solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), which apply to the entire Web IDE screen. | Solarized Light Theme | Solarized Dark Theme | Dark Theme | @@ -144,12 +144,13 @@ schemas: Each schema entry supports two properties: -- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL -is loaded when a matching file is open. -- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern, -it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`), -it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation -marks. Otherwise, the configuration file is not valid YAML. +- `uri`: please provide an absolute URL for the schema definition file here. + The schema from this URL is loaded when a matching file is open. +- `match`: a list of matching paths or glob expressions. If a schema matches a + particular path pattern, it is applied to that file. Please enclose the pattern + in quotes if it begins with an asterisk (`*`), it's be applied to that file. + If a pattern begins with an asterisk (`*`), enclose it in quotation marks. + Otherwise, the configuration file is not valid YAML. ## Configure the Web IDE @@ -180,7 +181,7 @@ The Web IDE currently supports the following `.editorconfig` settings: After making your changes, click the **Commit** button on the bottom-left to review the list of changed files. -Once you have finalized your changes, you can add a commit message, commit the +After you have finalized your changes, you can add a commit message, commit the changes and directly create a merge request. In case you don't have write access to the selected branch, you see a warning, but can still create a new branch and start a merge request. @@ -268,7 +269,7 @@ GitLab.com  -Once you have done that, you can preview projects with a `package.json` file and +After you have done that, you can preview projects with a `package.json` file and a `main` entry point inside the Web IDE. An example `package.json` is shown below. @@ -325,7 +326,7 @@ In order to enable the Web IDE terminals you need to create the file file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) syntax but with some restrictions: -- No global blocks can be defined (i.e., `before_script` or `after_script`) +- No global blocks (such as `before_script` or `after_script`) can be defined. - Only one job named `terminal` can be added to this file. - Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and `variables` are allowed to be used to configure the job. @@ -350,7 +351,7 @@ terminal: NODE_ENV: "test" ``` -Once the terminal has started, the console is displayed and we could access +After the terminal has started, the console is displayed and we could access the project repository files. **Important**. The terminal job is branch dependent. This means that the @@ -364,7 +365,7 @@ If there is no configuration file in a branch, an error message is shown. If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Click this button to open or close the terminal tab. -Once open, the tab shows the **Start Web Terminal** button. This button may +After opening, the tab shows the **Start Web Terminal** button. This button may be disabled if the environment is not configured correctly. If so, a status message describes the issue. Here are some reasons why **Start Web Terminal** may be disabled: @@ -378,7 +379,7 @@ can be closed and reopened and the state of the terminal is not affected. When the terminal is started and is successfully connected to the runner, then the runner's shell prompt appears in the terminal. From here, you can enter -commands executed within the runner's environment. This is similar +commands executed in the runner's environment. This is similar to running commands in a local terminal or through SSH. While the terminal is running, it can be stopped by clicking **Stop Terminal**. @@ -426,7 +427,7 @@ terminal: [predefined environment variable](../../../ci/variables/predefined_variables.md) for GitLab Runners. This is where your project's repository resides. -Once you have configured the web terminal for file syncing, then when the web +After you have configured the web terminal for file syncing, then when the web terminal is started, a **Terminal** status is visible in the status bar.  @@ -434,7 +435,7 @@ terminal is started, a **Terminal** status is visible in the status bar. Changes made to your files via the Web IDE sync to the running terminal when: -- <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac) +- <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac) is pressed while editing a file. - Anything outside the file editor is clicked after editing a file. - A file or folder is created, deleted, or renamed. @@ -446,7 +447,7 @@ The Web IDE has a few limitations: - Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, please note that the user is limited to having only one active terminal at a time. -- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository will be overwritten with the modified LFS file content. +- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. ### Troubleshooting diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 7802f2ba95e..779179a6665 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -204,13 +204,11 @@ otherwise they will not display when pushed to GitLab: ## Customizing sidebar -On the project's Wiki page, there is a right side navigation that renders the full Wiki pages list by default, with hierarchy. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by clicking the **Edit sidebar** button. -To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. +To customize the Wiki's navigation sidebar, you need Developer permissions to the project. -WARNING: -Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly -from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). +On the top-right, click **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. Example for `_sidebar` (using Markdown format): |
