diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-11-20 01:11:55 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-11-20 01:11:55 +0300 |
| commit | 5a8431feceba47fd8e1804d9aa1b1730606b71d5 (patch) | |
| tree | e5df8e0ceee60f4af8093f5c4c2f934b8abced05 /doc/user/project | |
| parent | 4d477238500c347c6553d335d920bedfc5a46869 (diff) | |
Add latest changes from gitlab-org/gitlab@12-5-stable-ee
Diffstat (limited to 'doc/user/project')
105 files changed, 2830 insertions, 1713 deletions
diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md new file mode 100644 index 00000000000..150a451dfe5 --- /dev/null +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -0,0 +1,730 @@ +# Adding and removing Kubernetes clusters + +GitLab can integrate with the following Kubernetes providers: + +- Google Kubernetes Engine (GKE). +- Amazon Elastic Kubernetes Service (EKS). + +TIP: **Tip:** +Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](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 GitLab's +Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. + +## Access controls + +When creating a cluster in GitLab, you will be asked if you would like to create either: + +- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster. +- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. + +NOTE: **Note:** +[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. + +GitLab creates the necessary service accounts and privileges to install and run +[GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster, +a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace +to manage the newly created cluster. + +NOTE: **Note:** +Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) in GitLab 11.5. + +When you install Helm into your cluster, the `tiller` service account +is created with `cluster-admin` privileges in the `gitlab-managed-apps` +namespace. + +This service account will be: + +- Added to the installed Helm Tiller +- Used by Helm to install and run [GitLab managed applications](index.md#installing-applications). + +Helm will also create additional service accounts and other resources for each +installed application. Consult the documentation of the Helm charts for each application +for details. + +If you are [adding an existing Kubernetes cluster](add_remove_clusters.md#add-existing-cluster), +ensure the token of the account has administrator privileges for the cluster. + +The resources created by GitLab differ depending on the type of cluster. + +### Important notes + +Note the following about access controls: + +- Environment-specific resources are only created if your cluster is + [managed by GitLab](index.md#gitlab-managed-clusters). +- If your cluster was created before GitLab 12.2, it will use a single namespace for all project + environments. + +### RBAC cluster resources + +GitLab creates the following resources for RBAC clusters. + +| Name | Type | Details | Created when | +|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:-----------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | +| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | +| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | +| Environment namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +### ABAC cluster resources + +GitLab creates the following resources for ABAC clusters. + +| Name | Type | Details | Created when | +|:----------------------|:---------------------|:-------------------------------------|:---------------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | +| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | +| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | + +### Security of GitLab Runners + +GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) +enabled by default, which allows them to execute special commands and running +Docker in Docker. This functionality is needed to run some of the +[Auto DevOps](../../../topics/autodevops/index.md) +jobs. This implies the containers are running in privileged mode and you should, +therefore, be aware of some important details. + +The privileged flag gives all capabilities to the running container, which in +turn can do almost everything that the host can do. Be aware of the +inherent security risk associated with performing `docker run` operations on +arbitrary images as they effectively have root access. + +If you don't want to use GitLab Runner in privileged mode, either: + +- Use shared Runners on GitLab.com. They don't have this security issue. +- Set up your own Runners using configuration described at + [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves: + 1. Making sure that you don't have it installed via + [the applications](index.md#installing-applications). + 1. Installing a Runner + [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). + +## Add new cluster + +### GKE cluster + +GitLab supports: + +- Creating a new GKE cluster using the GitLab UI. +- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster). + +Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). + +NOTE: **Note:** +The [Google authentication integration](../../../integration/google.md) must +be enabled in GitLab at the instance level. If that's not the case, ask your +GitLab administrator to enable it. On GitLab.com, this is enabled. + +#### GKE Requirements + +Before creating your first cluster on Google Kubernetes Engine with GitLab's +integration, make sure the following requirements are met: + +- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) + is set up and you have permissions to access it. +- The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the + ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). + +Also note the following: + +- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters + created by GitLab are RBAC-enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for + more information. +- Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/merge_requests/18341), the + cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR + notation. + +NOTE: **Note:** +GitLab requires basic authentication enabled and a client certificate issued for the cluster in +order to setup an [initial service account](#access-controls). Starting from [GitLab +11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will +explicitly request that basic authentication and client certificate is enabled. + +#### Creating the cluster on GKE + +If all of the above requirements are met, you can proceed to create and add a +new Kubernetes cluster to your project: + +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. + +1. Click **Add Kubernetes cluster**. +1. Click **Create with Google Kubernetes Engine**. +1. Connect your Google account if you haven't done already by clicking the + **Sign in with Google** button. +1. Choose your cluster's settings: + - **Kubernetes cluster name** - The name you wish to give the cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Google Cloud Platform project** - Choose the project you created in your GCP + console that will host the Kubernetes cluster. Learn more about + [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) + under which the cluster will be created. + - **Number of nodes** - Enter the number of nodes you wish the cluster to have. + - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) + of the Virtual Machine instance that the cluster will be based on. + - **Enable Cloud Run on GKE (beta)** - Check this if you want to use Cloud Run on GKE for this cluster. + See the [Cloud Run on GKE section](#cloud-run-on-gke) for more information. + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. +1. Finally, click the **Create Kubernetes cluster** button. + +After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](index.md#installing-applications). + +#### Cloud Run on GKE + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16566) in GitLab 12.4. + +You can choose to use Cloud Run on GKE in place of installing Knative and Istio +separately after the cluster has been created. This means that Cloud Run +(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at +create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. + +### EKS Cluster + +GitLab supports: + +- Creating a new EKS cluster using the GitLab UI + ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5). +- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster). + +#### EKS Requirements + +Before creating your first cluster on Amazon EKS with GitLab's integration, +make sure the following requirements are met: + +- An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. +- You have permissions to manage IAM resources. + +##### Additional requirements for self-managed instances + +If you are using a self-managed GitLab instance, GitLab must first +be configured with a set of Amazon credentials. These credentials +will be used to assume an Amazon IAM role provided by the user +creating the cluster. Create an IAM user and ensure it has permissions +to assume the role(s) that your users will use to create EKS clusters. + +For example, the following policy document allows assuming a role whose name starts with +`gitlab-eks-` in account `123456789012`: + +```json +{ + "Version": "2012-10-17", + "Statement": { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*" + } +} +``` + +Generate an access key for the IAM user, and configure GitLab with the credentials: + +1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section. +1. Check **Enable Amazon EKS integration**. +1. Enter the account ID and access key credentials into the respective + `Account ID`, `Access key ID` and `Secret access key` fields. +1. Click **Save changes**. + +#### Creating the cluster on EKS + +If all of the above requirements are met, you can proceed to create and add a +new Kubernetes cluster to your project: + +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. + +1. Click **Add Kubernetes cluster**. +1. Click **Amazon EKS**. You will be provided with an `Account ID` and `External ID` to use in the next step. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: + 1. From the left panel, select **Roles**. + 1. Click **Create role**. + 1. Under `Select type of trusted entity`, select **Another AWS account**. + 1. Enter the Account ID from GitLab into the `Account ID` field. + 1. Check **Require external ID**. + 1. Enter the External ID from GitLab into the `External ID` field. + 1. Click **Next: Permissions**. + 1. Click **Create Policy**, which will open a new window. + 1. Select the **JSON** tab, and paste in the following snippet in place of the existing content: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "autoscaling:CreateAutoScalingGroup", + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:DescribeScalingActivities", + "autoscaling:UpdateAutoScalingGroup", + "autoscaling:CreateLaunchConfiguration", + "autoscaling:DescribeLaunchConfigurations", + "cloudformation:CreateStack", + "cloudformation:DescribeStacks", + "ec2:AuthorizeSecurityGroupEgress", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:RevokeSecurityGroupEgress", + "ec2:RevokeSecurityGroupIngress", + "ec2:CreateSecurityGroup", + "ec2:createTags", + "ec2:DescribeImages", + "ec2:DescribeKeyPairs", + "ec2:DescribeRegions", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ec2:DescribeVpcs", + "eks:CreateCluster", + "eks:DescribeCluster", + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateRole", + "iam:CreateInstanceProfile", + "iam:GetRole", + "iam:ListRoles", + "iam:PassRole", + "ssm:GetParameters" + ], + "Resource": "*" + } + ] + } + ``` + + NOTE: **Note:** + These permissions give GitLab the ability to create resources, but not delete them. + This means that if an error is encountered during the creation process, changes will + not be rolled back and you must remove resources manually. You can do this by deleting + the relevant [CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html) + + 1. Click **Review policy**. + 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. + 1. Switch back to the "Create role" window, and select the policy you just created. + 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. + 1. Click **Next: Review**. + 1. Enter a role name and optional description into the fields provided. + 1. Click **Create role**, the new role name will appear at the top. Click on its name and copy the `Role ARN` from the newly created role. +1. In GitLab, enter the copied role ARN into the `Role ARN` field. +1. Click **Authenticate with AWS**. +1. Choose your cluster's settings: + - **Kubernetes cluster name** - The name you wish to give the cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. + - **Role name** - Select the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) + to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. + - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) + in which the cluster will be created. + - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) + that you can use to connect to your worker nodes if required. + - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) + to use for your EKS Cluster resources. + - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) + in your VPC where your worker nodes will run. + - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) + to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. + - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. + - **Node count** - The number of worker nodes. + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. +1. Finally, click the **Create Kubernetes cluster** button. + +After about 10 minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](index.md#installing-applications). + +## Add existing cluster + +If you have either of the following types of clusters already, you can add them to a project: + +- [Google Kubernetes Engine cluster](#add-existing-gke-cluster). +- [Amazon Elastic Kubernetes Service](#add-existing-eks-cluster). + +NOTE: **Note:** +Kubernetes integration is not supported for arm64 clusters. See the issue +[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. + +### Add existing GKE cluster + +To add an existing Kubernetes cluster to your project: + +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. + +1. Click **Add Kubernetes cluster**. +1. Click **Add an existing Kubernetes cluster** and fill in the details: + - **Kubernetes cluster name** (required) - The name you wish to give the cluster. + - **Environment scope** (required) - The + [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **API URL** (required) - + It's the URL that GitLab uses to access the Kubernetes API. Kubernetes + exposes several APIs, we want the "base" URL that is common to all of them, + e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```sh + kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + ``` + + - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate by running this command: + + ```sh + + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + + ``` + + NOTE: **Note:** + If the command returns the entire certificate chain, you need copy the *root ca* + certificate at the bottom of the chain. + + - **Token** - + GitLab authenticates against Kubernetes using service tokens, which are + scoped to a particular `namespace`. + **The token used should belong to a service account with + [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges.** To create this service account: + + 1. Create a file called `gitlab-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```bash + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + You will need the `container.clusterRoleBindings.create` permission + to create cluster-level roles. If you do not have this permission, + you can alternatively enable Basic Authentication and then run the + `kubectl apply` command as an admin: + + ```bash + kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> + ``` + + NOTE: **Note:** + Basic Authentication can be turned on and the password credentials + can be obtained using the Google Cloud Console. + + Output: + + ```bash + serviceaccount "gitlab-admin" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + role binding. You can follow the [Google Cloud + documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. + + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. + + - **Project namespace** (optional) - You don't have to fill it in; by leaving + it blank, GitLab will create one for you. Also: + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. + +1. Finally, click the **Create Kubernetes cluster** button. + +After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](index.md#installing-applications). + +### Add existing EKS cluster + +In this section, we will show how to integrate an [Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin +deploying applications. + +#### Requirements + +To integrate with with EKS, you will need: + +- An account on GitLab, like [GitLab.com](https://gitlab.com). +- An Amazon EKS cluster (with worker nodes properly configured). +- `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). + +If you don't have an Amazon EKS cluster, one can be created by following the +[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). + +#### Configuring and connecting the EKS cluster + +From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, +then click **Add an existing Kubernetes cluster**. + +A few details from the EKS cluster will be required to connect it to GitLab: + +1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to + authenticate to the EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: + + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate with: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + +1. **Create admin token**: A `cluster-admin` token is required to install and + manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller + and creates limited service accounts for each application. To create the + token we will create an admin service account as follows: + + 1. Create a file called `eks-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` + + 1. Apply the service account to your cluster: + + ```bash + kubectl apply -f eks-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "eks-admin" created + ``` + + 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` + + 1. Apply the cluster role binding to your cluster: + + ```bash + kubectl apply -f eks-admin-cluster-role-binding.yaml + ``` + + Output: + + ```bash + clusterrolebinding "eks-admin" created + ``` + + 1. Retrieve the token for the `eks-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + +1. The API server endpoint is also required, so GitLab can connect to the cluster. + This is displayed on the AWS EKS console, when viewing the EKS cluster details. + +You now have all the information needed to connect the EKS cluster: + +- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. +- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. +- API URL: Paste in the API server endpoint retrieved above. +- CA Certificate: Paste the certificate data from the earlier step, as-is. +- Paste the admin token value. +- Project namespace: This can be left blank to accept the default namespace, based on the project name. + + + +Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. +At this point, [Kubernetes deployment variables](index.md#deployment-variables) will +automatically be available during CI/CD jobs, making it easy to interact with the cluster. + +If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. + +#### Disable Role-Based Access Control (RBAC) (optional) + +When connecting a cluster via GitLab integration, you may specify whether the +cluster is RBAC-enabled or not. This will affect how GitLab interacts with the +cluster for certain operations. If you **did not** check the "RBAC-enabled cluster" +checkbox at creation time, GitLab will assume RBAC is disabled for your cluster +when interacting with it. If so, you must disable RBAC on your cluster for the +integration to work properly. + + + +NOTE: **Note**: Disabling RBAC means that any application running in the cluster, +or user who can authenticate to the cluster, has full API access. This is a +[security concern](index.md#security-implications), and may not be desirable. + +To effectively disable RBAC, global permissions can be applied granting full access: + +```bash +kubectl create clusterrolebinding permissive-binding \ + --clusterrole=cluster-admin \ + --user=admin \ + --user=kubelet \ + --group=system:serviceaccounts +``` + +#### Create a default Storage Class + +Amazon EKS doesn't have a default Storage Class out of the box, which means +requests for persistent volumes will not be automatically fulfilled. As part +of Auto DevOps, the deployed Postgres instance requests persistent storage, +and without a default storage class it will fail to start. + +If a default Storage Class doesn't already exist and is desired, follow Amazon's +[guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) +to create one. + +Alternatively, disable Postgres by setting the project variable +[`POSTGRES_ENABLED`](../../../topics/autodevops/#environment-variables) to `false`. + +#### Deploy the app to EKS + +With RBAC disabled and services deployed, +[Auto DevOps](../../../topics/autodevops/index.md) can now be leveraged +to build, test, and deploy the app. + +[Enable Auto DevOps](../../../topics/autodevops/index.md#at-the-project-level) +if not already enabled. If a wildcard DNS entry was created resolving to the +Load Balancer, enter it in the `domain` field under the Auto DevOps settings. +Otherwise, the deployed app will not be externally available outside of the cluster. + + + +A new pipeline will automatically be created, which will begin to build, test, +and deploy the app. + +After the pipeline has finished, your app will be running in EKS and available +to users. Click on **CI/CD > Environments**. + + + +You will see a list of the environments and their deploy status, as well as +options to browse to the app, view monitoring metrics, and even access a shell +on the running pod. + +## Enabling or disabling integration + +After you have successfully added your cluster information, you can enable the +Kubernetes cluster integration: + +1. Click the **Enabled/Disabled** switch +1. Hit **Save** for the changes to take effect + +To disable the Kubernetes cluster integration, follow the same procedure. + +## Removing integration + +To remove the Kubernetes cluster integration from your project, simply click the +**Remove integration** button. You will then be able to follow the procedure +and add a Kubernetes cluster again. + +When removing the cluster integration, note: + +- You need Maintainer [permissions](../../permissions.md) and above to remove a Kubernetes cluster + integration. +- When you remove a cluster, you only remove its relationship to GitLab, not the cluster itself. To + remove the cluster, you can do so by visiting the GKE dashboard or using `kubectl`. + +## Learn more + +To learn more on automatically deploying your applications, +read about [Auto DevOps](../../../topics/autodevops/index.md). diff --git a/doc/user/project/clusters/eks_and_gitlab/img/create_dns.png b/doc/user/project/clusters/eks_and_gitlab/img/create_dns.png Binary files differdeleted file mode 100644 index 61ed85e5cd9..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/create_dns.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/img/create_project.png b/doc/user/project/clusters/eks_and_gitlab/img/create_project.png Binary files differdeleted file mode 100644 index b02ab4b9064..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/create_project.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/img/deploy_apps.png b/doc/user/project/clusters/eks_and_gitlab/img/deploy_apps.png Binary files differdeleted file mode 100644 index 0d9fcc838d9..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/deploy_apps.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 22576b84926..fda8cd6340e 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -1,278 +1,5 @@ -# Connecting and deploying to an Amazon EKS cluster +--- +redirect_to: '../add_remove_clusters.md#add-existing-eks-cluster' +--- -In this tutorial, we will show how to integrate an -[Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin -deploying applications. - -## Introduction - -For an end-to-end walkthrough we will: - -1. Start with a new project based on the sample Ruby on Rails template. -1. Integrate an EKS cluster. -1. Utilize [Auto DevOps](../../../../topics/autodevops/) to build, test, and deploy our application. - -You will need: - -1. An account on GitLab, like [GitLab.com](https://gitlab.com). -1. An Amazon EKS cluster (with worker nodes properly configured). -1. `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). - -If you don't have an Amazon EKS cluster, one can be created by following the -[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). - -## Creating a new project - -On GitLab, create a new project by clicking on the `+` icon in the top navigation -bar and selecting **New project**. - -On the new project screen, click on the **Create from template** tab, and select -"Use template" for the Ruby on Rails sample project. - -Give the project a name, and then select **Create project**. - - - -## Configuring and connecting the EKS cluster - -From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, -then click **Add an existing Kubernetes cluster**. - -A few details from the EKS cluster will be required to connect it to GitLab: - -1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to - authenticate to the EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: - - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate with: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - -1. **Create admin token**: A `cluster-admin` token is required to install and - manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller - and creates limited service accounts for each application. To create the - token we will create an admin service account as follows: - - 2.1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 2.2. Apply the service account to your cluster: - - ```bash - kubectl apply -f eks-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "eks-admin" created - ``` - - 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 2.4. Apply the cluster role binding to your cluster: - - ```bash - kubectl apply -f eks-admin-cluster-role-binding.yaml - ``` - - Output: - - ```bash - clusterrolebinding "eks-admin" created - ``` - - 2.5. Retrieve the token for the `eks-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - -1. The API server endpoint is also required, so GitLab can connect to the cluster. - This is displayed on the AWS EKS console, when viewing the EKS cluster details. - -You now have all the information needed to connect the EKS cluster: - -- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. -- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. -- API URL: Paste in the API server endpoint retrieved above. -- CA Certificate: Paste the certificate data from the earlier step, as-is. -- Paste the admin token value. -- Project namespace: This can be left blank to accept the default namespace, based on the project name. - - - -Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. -At this point, [Kubernetes deployment variables](../#deployment-variables) will -automatically be available during CI/CD jobs, making it easy to interact with the cluster. - -If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. - -## Disable Role-Based Access Control (RBAC) (optional) - -When connecting a cluster via GitLab integration, you may specify whether the -cluster is RBAC-enabled or not. This will affect how GitLab interacts with the -cluster for certain operations. If you **did not** check the "RBAC-enabled cluster" -checkbox at creation time, GitLab will assume RBAC is disabled for your cluster -when interacting with it. If so, you must disable RBAC on your cluster for the -integration to work properly. - - - -NOTE: **Note**: Disabling RBAC means that any application running in the cluster, -or user who can authenticate to the cluster, has full API access. This is a -[security concern](../index.md#security-implications), and may not be desirable. - -To effectively disable RBAC, global permissions can be applied granting full access: - -```bash -kubectl create clusterrolebinding permissive-binding \ - --clusterrole=cluster-admin \ - --user=admin \ - --user=kubelet \ - --group=system:serviceaccounts -``` - -## Deploy services to the cluster - -GitLab supports one-click deployment of helpful services to the cluster, many of -which support Auto DevOps. Back on the Kubernetes cluster screen in GitLab, a -list of applications is now available to deploy. - -First, install Helm Tiller, a package manager for Kubernetes. This enables -deployment of the other applications. - - - -### Deploying NGINX Ingress (optional) - -Next, if you would like the deployed app to be reachable on the internet, deploy -the Ingress. Note that this will also cause an -[Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) -to be created, which will incur additional AWS costs. - -Once installed, you may see a `?` for "Ingress IP Address". This is because the -created ELB is available at a DNS name, not an IP address. To get the DNS name, -run: - -```sh -kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}" -``` - -Note that you may see a trailing `%` on some Kubernetes versions, **do not include it**. - -The Ingress is now available at this address and will route incoming requests to -the proper service based on the DNS name in the request. To support this, a -wildcard DNS CNAME record should be created for the desired domain name. For example, -`*.myekscluster.com` would point to the Ingress hostname obtained earlier. - - - -### Deploying the GitLab Runner (optional) - -If the project is on GitLab.com, free shared Runners are available and you do -not have to deploy one. If a project specific Runner is desired, or there are no -shared Runners, it is easy to deploy one. - -Simply click on the **Install** button for the GitLab Runner. It is important to -note that the Runner deployed is set as **privileged**, which means it essentially -has root access to the underlying machine. This is required to build docker images, -and so is on by default. - -### Deploying Prometheus (optional) - -GitLab is able to monitor applications automatically, utilizing -[Prometheus](../../integrations/prometheus.html). Kubernetes container CPU and -memory metrics are automatically collected, and response metrics are retrieved -from NGINX Ingress as well. - -To enable monitoring, simply install Prometheus into the cluster with the -**Install** button. - -## Create a default Storage Class - -Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes will not be automatically fulfilled. As part -of Auto DevOps, the deployed Postgres instance requests persistent storage, -and without a default storage class it will fail to start. - -If a default Storage Class doesn't already exist and is desired, follow Amazon's -[guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) -to create one. - -Alternatively, disable Postgres by setting the project variable -[`POSTGRES_ENABLED`](../../../../topics/autodevops/#environment-variables) to `false`. - -## Deploy the app to EKS - -With RBAC disabled and services deployed, -[Auto DevOps](../../../../topics/autodevops/index.md) can now be leveraged -to build, test, and deploy the app. - -[Enable Auto DevOps](../../../../topics/autodevops/index.md#at-the-project-level) -if not already enabled. If a wildcard DNS entry was created resolving to the -Load Balancer, enter it in the `domain` field under the Auto DevOps settings. -Otherwise, the deployed app will not be externally available outside of the cluster. - - - -A new pipeline will automatically be created, which will begin to build, test, -and deploy the app. - -After the pipeline has finished, your app will be running in EKS and available -to users. Click on **CI/CD > Environments**. - - - -You will see a list of the environments and their deploy status, as well as -options to browse to the app, view monitoring metrics, and even access a shell -on the running pod. - -## Learn more - -To learn more on automatically deploying your applications, -read about [Auto DevOps](../../../../topics/autodevops/index.md). +This document was moved to [another location](../add_remove_clusters.md#add-existing-eks-cluster). diff --git a/doc/user/project/clusters/eks_and_gitlab/img/add_cluster.png b/doc/user/project/clusters/img/add_cluster.png Binary files differindex 94ec83f1514..94ec83f1514 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/add_cluster.png +++ b/doc/user/project/clusters/img/add_cluster.png diff --git a/doc/user/project/clusters/eks_and_gitlab/img/environment.png b/doc/user/project/clusters/img/environment.png Binary files differindex 4714c447026..4714c447026 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/environment.png +++ b/doc/user/project/clusters/img/environment.png diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs_v12_4.png b/doc/user/project/clusters/img/kubernetes_pod_logs_v12_4.png Binary files differdeleted file mode 100644 index 73c2ecd182a..00000000000 --- a/doc/user/project/clusters/img/kubernetes_pod_logs_v12_4.png +++ /dev/null diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs_v12_5.png b/doc/user/project/clusters/img/kubernetes_pod_logs_v12_5.png Binary files differnew file mode 100644 index 00000000000..e54637e7218 --- /dev/null +++ b/doc/user/project/clusters/img/kubernetes_pod_logs_v12_5.png diff --git a/doc/user/project/clusters/eks_and_gitlab/img/pipeline.png b/doc/user/project/clusters/img/pipeline.png Binary files differindex 0eb00d0faa7..0eb00d0faa7 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/pipeline.png +++ b/doc/user/project/clusters/img/pipeline.png diff --git a/doc/user/project/clusters/eks_and_gitlab/img/rbac.png b/doc/user/project/clusters/img/rbac.png Binary files differindex 517e4f7ca44..517e4f7ca44 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/rbac.png +++ b/doc/user/project/clusters/img/rbac.png diff --git a/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_5.png b/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_5.png Binary files differnew file mode 100644 index 00000000000..f113b0353f2 --- /dev/null +++ b/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_5.png diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 9ecb785d6fe..c5c2c2c07e7 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -28,12 +28,11 @@ Using the GitLab project Kubernetes integration, you can: - Use [Deploy Boards](#deploy-boards-premium). **(PREMIUM)** - Use [Canary Deployments](#canary-deployments-premium). **(PREMIUM)** - View [Pod logs](#pod-logs-ultimate). **(ULTIMATE)** - -You can also: - -- Connect and deploy to an [Amazon EKS cluster](eks_and_gitlab/index.html). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). +See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to +set up integrations. + ### Deploy Boards **(PREMIUM)** GitLab's Deploy Boards offer a consolidated view of the current health and @@ -98,236 +97,10 @@ pods are annotated with: `$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. -## Adding and removing clusters - -There are two options when adding a new cluster to your project: - -- Associate your account with Google Kubernetes Engine (GKE) to - [create new clusters](#add-new-gke-cluster) from within GitLab. -- Provide credentials to an - [existing Kubernetes cluster](#add-existing-kubernetes-cluster). - -### Add new GKE cluster - -TIP: **Tip:** -Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](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 GitLab's -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. - -NOTE: **Note:** -The [Google authentication integration](../../../integration/google.md) must -be enabled in GitLab at the instance level. If that's not the case, ask your -GitLab administrator to enable it. On GitLab.com, this is enabled. - -#### Requirements - -Before creating your first cluster on Google Kubernetes Engine with GitLab's -integration, make sure the following requirements are met: - -- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) - is set up and you have permissions to access it. -- The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the - ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). - -#### Creating the cluster - -If all of the above requirements are met, you can proceed to create and add a -new Kubernetes cluster to your project: - -1. Navigate to your project's **Operations > Kubernetes** page. - - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. - -1. Click **Add Kubernetes cluster**. -1. Click **Create with Google Kubernetes Engine**. -1. Connect your Google account if you haven't done already by clicking the - **Sign in with Google** button. -1. From there on, choose your cluster's settings: - - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](#setting-the-environment-scope-premium) to this cluster. - - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about - [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. - - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. - - **Enable Cloud Run on GKE (beta)** - Check this if you want to use Cloud Run on GKE for this cluster. See the [Cloud Run on GKE section](#cloud-run-on-gke) for more information. - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. -1. Finally, click the **Create Kubernetes cluster** button. - -After a couple of minutes, your cluster will be ready to go. You can now proceed -to install some [pre-defined applications](#installing-applications). - -NOTE: **Note:** -GitLab requires basic authentication enabled and a client certificate issued for -the cluster in order to setup an [initial service -account](#access-controls). Starting from [GitLab -11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster -creation process will explicitly request that basic authentication and -client certificate is enabled. - -NOTE: **Note:** -Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters created by GitLab are RBAC enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for more information. - -### Add existing Kubernetes cluster - -NOTE: **Note:** -Kubernetes integration is not supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. - -To add an existing Kubernetes cluster to your project: - -1. Navigate to your project's **Operations > Kubernetes** page. - - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. - -1. Click **Add Kubernetes cluster**. -1. Click **Add an existing Kubernetes cluster** and fill in the details: - - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required) - The - [associated environment](#setting-the-environment-scope-premium) to this cluster. - - **API URL** (required) - - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes - exposes several APIs, we want the "base" URL that is common to all of them, - e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - Get the API URL by running this command: - - ```sh - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' - ``` - - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - - **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. - **The token used should belong to a service account with - [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges.** To create this service account: - - 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```bash - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "gitlab-admin" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - NOTE: **Note:** - For GKE clusters, you will need the - `container.clusterRoleBindings.create` permission to create a cluster - role binding. You can follow the [Google Cloud - documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) - to grant access. - - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. - - - **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab will create one for you. Also: - - Each project should have a unique namespace. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. - -1. Finally, click the **Create Kubernetes cluster** button. - -After a couple of minutes, your cluster will be ready to go. You can now proceed -to install some [pre-defined applications](#installing-applications). - -### Enabling or disabling integration - -After you have successfully added your cluster information, you can enable the -Kubernetes cluster integration: - -1. Click the **Enabled/Disabled** switch -1. Hit **Save** for the changes to take effect - -To disable the Kubernetes cluster integration, follow the same procedure. - -### Removing integration - -NOTE: **Note:** -You need Maintainer [permissions](../../permissions.md) and above to remove a Kubernetes cluster integration. - -NOTE: **Note:** -When you remove a cluster, you only remove its relation to GitLab, not the -cluster itself. To remove the cluster, you can do so by visiting the GKE -dashboard or using `kubectl`. - -To remove the Kubernetes cluster integration from your project, simply click the -**Remove integration** button. You will then be able to follow the procedure -and add a Kubernetes cluster again. - ## Cluster configuration -This section covers important considerations for configuring Kubernetes -clusters with GitLab. +After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers +important considerations for configuring Kubernetes clusters with GitLab. ### Security implications @@ -340,15 +113,6 @@ functionalities needed to successfully build and deploy a containerized application. Bear in mind that the same credentials are used for all the applications running on the cluster. -### Cloud Run on GKE - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16566) in GitLab 12.4. - -You can choose to use Cloud Run on GKE in place of installing Knative and Istio -separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at -create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. - ### GitLab-managed clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5. @@ -356,7 +120,7 @@ create time and cannot be [installed or uninstalled](../../clusters/applications You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](#access-controls) section for details on which resources will +[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will be created. If you choose to manage your own cluster, project-specific resources will not be created @@ -386,97 +150,6 @@ you can either: - Create an `A` record that points to the Ingress IP address with your domain provider. - Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`. -### Access controls - -When creating a cluster in GitLab, you will be asked if you would like to create either: - -- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. -- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster. - -NOTE: **Note:** -[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. - -GitLab creates the necessary service accounts and privileges to install and run -[GitLab managed applications](#installing-applications). When GitLab creates the cluster, -a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace -to manage the newly created cluster. - - NOTE: **Note:** - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) in GitLab 11.5. - -When you install Helm into your cluster, the `tiller` service account -is created with `cluster-admin` privileges in the `gitlab-managed-apps` -namespace. This service account will be added to the installed Helm Tiller and will -be used by Helm to install and run [GitLab managed applications](#installing-applications). -Helm will also create additional service accounts and other resources for each -installed application. Consult the documentation of the Helm charts for each application -for details. - -If you are [adding an existing Kubernetes cluster](#add-existing-kubernetes-cluster), -ensure the token of the account has administrator privileges for the cluster. - -The resources created by GitLab differ depending on the type of cluster. - -#### ABAC cluster resources - -GitLab creates the following resources for ABAC clusters. - -| Name | Type | Details | Created when | -|:----------------------|:---------------------|:-------------------------------------|:---------------------------| -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | -| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | -| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | - -#### RBAC cluster resources - -GitLab creates the following resources for RBAC clusters. - -| Name | Type | Details | Created when | -|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------| -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | -| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | -| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -| Environment namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | - -NOTE: **Note:** -Environment-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters). - -NOTE: **Note:** -If your cluster was created before GitLab 12.2, it will use a single namespace for all project environments. - -#### Security of GitLab Runners - -GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) -enabled by default, which allows them to execute special commands and running -Docker in Docker. This functionality is needed to run some of the -[Auto DevOps](../../../topics/autodevops/index.md) -jobs. This implies the containers are running in privileged mode and you should, -therefore, be aware of some important details. - -The privileged flag gives all capabilities to the running container, which in -turn can do almost everything that the host can do. Be aware of the -inherent security risk associated with performing `docker run` operations on -arbitrary images as they effectively have root access. - -If you don't want to use GitLab Runner in privileged mode, either: - -- Use shared Runners on GitLab.com. They don't have this security issue. -- Set up your own Runners using configuration described at - [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves: - 1. Making sure that you don't have it installed via - [the applications](#installing-applications). - 1. Installing a Runner - [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). - ### Setting the environment scope **(PREMIUM)** When adding more than one Kubernetes cluster to your project, you need to differentiate @@ -545,93 +218,12 @@ differentiate the new cluster with the rest. ## Installing applications -GitLab can install and manage some applications in your project-level -cluster. For more information on installing, upgrading, uninstalling, -and troubleshooting applications for your project cluster, see +GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, +Prometheus, etc., in your project-level cluster. For more information on +installing, upgrading, uninstalling, and troubleshooting applications for +your project cluster, see [GitLab Managed Apps](../../clusters/applications.md). -### Getting the external endpoint - -NOTE: **Note:** -With the following procedure, a load balancer must be installed in your cluster -to obtain the endpoint. You can use either -[Ingress](#installing-applications), or Knative's own load balancer -([Istio](https://istio.io)) if using [Knative](#installing-applications). - -In order to publish your web application, you first need to find the endpoint which will be either an IP -address or a hostname associated with your load balancer. - -#### Automatically determining the external endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/17052) in GitLab 10.6. - -After you install [Ingress or Knative](#installing-applications), GitLab attempts to determine the external endpoint -and it should be available within a few minutes. If the endpoint doesn't appear -and your cluster runs on Google Kubernetes Engine: - -1. Check your [Kubernetes cluster on Google Kubernetes Engine](https://console.cloud.google.com/kubernetes) to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) on Google Kubernetes Engine. For more information, see [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Check [Google Cloud's Status](https://status.cloud.google.com/) to ensure they are not having any disruptions. - -If GitLab is still unable to determine the endpoint of your Ingress or Knative application, you can -manually determine it by following the steps below. - -#### Manually determining the external endpoint - -If the cluster is on GKE, click the **Google Kubernetes Engine** link in the -**Advanced settings**, or go directly to the -[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click **Connect** and execute -the `gcloud` command in a local terminal or using the **Cloud Shell**. - -If the cluster is not on GKE, follow the specific instructions for your -Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples will show the external endpoint of your -cluster. This information can then be used to set up DNS entries and forwarding -rules that allow external access to your deployed applications. - -If you installed the Ingress [via the **Applications**](#installing-applications), -run the following command: - -```bash -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` - -Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: - -```bash -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' -``` - -For Istio/Knative, the command will be different: - -```bash -kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' -``` - -Otherwise, you can list the IP addresses of all load balancers: - -```bash -kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' -``` - -#### Using a static IP - -By default, an ephemeral external IP address is associated to the cluster's load -balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps will not be able to be reached, and you'd have to change the DNS -record again. In order to avoid that, you should change it into a static -reserved IP. - -Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). - -#### Pointing your DNS at the external endpoint - -Once you've set up the external endpoint, you should associate it with a [wildcard DNS -record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) such as `*.example.com.` -in order to be able to reach your apps. If your external endpoint is an IP address, -use an A record. If your external endpoint is a hostname, use a CNAME record. - ## Deploying to a Kubernetes cluster A Kubernetes cluster can be the destination for a deployment job. If @@ -654,8 +246,8 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](#access-controls). | -| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>-<environment>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. | | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | @@ -668,6 +260,16 @@ service account of the cluster integration. NOTE: **Note:** If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`. +When deploying a custom namespace: + +- The custom namespace must exist in your cluster. +- The project's deployment service account must have permission to deploy to the namespace. +- `KUBECONFIG` must be updated to use the custom namespace instead of the GitLab-provided default (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/issues/31519)). +- If deploying with Auto DevOps, you must *also* override `KUBE_NAMESPACE` with the custom namespace. + +CAUTION: **Caution:** +GitLab does not save custom namespaces in the database. So while deployments work with custom namespaces, GitLab's integration for already-deployed environments will not pick up the customized values. For example, [Deploy Boards](../deploy_boards.md) will not work as intended for those deployments. For more information, see the [related issue](https://gitlab.com/gitlab-org/gitlab/issues/27630). + ### Troubleshooting Before the deployment jobs starts, GitLab creates the following specifically for diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 4036eaf0bfb..797ddf784cc 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -11,7 +11,31 @@ Everything you need to build, test, deploy, and run your app at scale. ## Overview -[Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): +[Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. + + + +## Requirements + +[Deploying to a Kubernetes environment](../deploy_boards.md#enabling-deploy-boards) is required in order to be able to use Pod Logs. + +## Usage + +To access pod logs, you must have the right [permissions](../../permissions.md#project-members-permissions). + +You can access them in two ways. + +### From the project sidebar + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 12.5. + +Go to **Operations > Pod logs** on the sidebar menu. + + + +### From Deploy Boards + +Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): 1. Go to **Operations > Environments** and find the environment which contains the desired pod, like `production`. 1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). @@ -23,9 +47,3 @@ Everything you need to build, test, deploy, and run your app at scale. - [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/6502). - -  - -## Requirements - -[Enabling Deploy Boards](../deploy_boards.md#enabling-deploy-boards) is required in order to be able to use Pod Logs. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 7b17ec68234..bffae4c5069 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -35,7 +35,7 @@ for an overview of how this is accomplished in GitLab!** To create an executable runbook, you will need: 1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#add-new-gke-cluster). + The simplest way to get started is to add a cluster using one of [GitLab's integrations](../add_remove_clusters.md#add-new-cluster). 1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the Helm CLI in a safe environment. @@ -60,7 +60,7 @@ the components outlined above and the preloaded demo runbook. ### 1. Add a Kubernetes cluster -Follow the steps outlined in [Add new GKE cluster](../index.md#add-new-gke-cluster) +Follow the steps outlined in [Add new cluster](../add_remove_clusters.md#add-new-cluster) to add a Kubernetes cluster to your project. ### 2. Install Helm Tiller, Ingress, and JupyterHub diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 9a9857bd5da..ffd7b0c0f2a 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -13,14 +13,16 @@ GitLab supports several ways deploy Serverless applications in both Kubernetes E Currently we support: -- [Knative](#knative): Build Knative applications with Knative and gitlabktl on GKE -- [AWS Lambda](aws.md): Create serverless applications via the Serverless Framework and GitLab CI +- [Knative](#knative): Build Knative applications with Knative and gitlabktl on GKE. +- [AWS Lambda](aws.md): Create serverless applications via the Serverless Framework and GitLab CI. ## Knative Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). -Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, container-based applications. Knative brings some significant benefits out of the box through its main components: +Knative extends Kubernetes to provide a set of middleware components that are useful to build +modern, source-centric, container-based applications. Knative brings some significant benefits out +of the box through its main components: - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. - [Eventing](https://github.com/knative/eventing): Management and delivery of events. @@ -39,7 +41,7 @@ To run Knative on GitLab, you will need: - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#add-new-gke-cluster). + The simplest way to get started is to add a cluster using [GitLab's GKE integration](../add_remove_clusters.md#gke-cluster). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install Knative. @@ -62,20 +64,22 @@ To run Knative on GitLab, you will need: using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. See [Installing Applications](../index.md#installing-applications) for more information. +1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. + See [Configuring logging](#configuring-logging) for more information. ## Installing Knative via GitLab's Kubernetes integration NOTE: **Note:** The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** -1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications). +1. [Add a Kubernetes cluster](../add_remove_clusters.md) and [install Helm](../index.md#installing-applications). 1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with your application/functions (e.g. `example.com`) and click **Install**.  1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the - **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../#manually-determining-the-external-endpoint). + **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). NOTE: **Note:** Running `kubectl` commands on your cluster requires setting up access to the cluster first. @@ -108,7 +112,7 @@ You must do the following: 1. Follow the steps to [add an existing Kubernetes - cluster](../index.md#add-existing-kubernetes-cluster). + cluster](../add_remove_clusters.md#add-existing-cluster). 1. Ensure GitLab can manage Knative: - For a non-GitLab managed cluster, ensure that the service account for the token @@ -164,13 +168,61 @@ You must do the following: or [serverless applications](#deploying-serverless-applications) onto your cluster. -## Deploying functions +## Configuring logging -> Introduced in GitLab 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33330) in GitLab 12.5. + +### Prerequisites + +- A GitLab-managed cluster. +- `kubectl` installed and working. + +Running `kubectl` commands on your cluster requires setting up access to the +cluster first. For clusters created on: + +- GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) +- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +### Enable request log template + +Run the following command to enable request logs: + +```shell +kubectl edit cm -n knative-serving config-observability +``` + +Copy the `logging.request-log-template` from the `data._example` field to the data field one level up in the hierarchy. + +### Enable request logs + +Run the following commands to install Elasticsearch, Kibana, and Filebeat into a `kube-logging` namespace and configure all nodes to forward logs using Filebeat: -Using functions is useful for dealing with independent events without needing -to maintain a complex unified infrastructure. This allows you to focus on a -single task that can be executed/scaled automatically and independently. +```shell +kubectl apply -f https://gitlab.com/gitlab-org/serverless/configurations/knative/raw/v0.7.0/kube-logging-filebeat.yaml +kubectl label nodes --all beta.kubernetes.io/filebeat-ready="true" +``` + +### Viewing request logs + +To view request logs: + +1. Run `kubectl proxy`. +1. Navigate to Kibana UI. + +Or: + +1. Open the Kibana UI. +1. Click on **Discover**, then select `filebeat-*` from the dropdown on the left. +1. Enter `kubernetes.container.name:"queue-proxy" AND message:/httpRequest/` into the search box. + +## Supported runtimes + +Serverless functions for GitLab can be written in 6 supported languages: + +- NodeJS and Ruby, with GitLab-managed and OpenFaas runtimes. +- C#, Go, PHP, and Python with OpenFaaS runtimes only. + +### GitLab managed runtimes Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered: @@ -180,6 +232,31 @@ Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runt `Dockerfile` presence is assumed when a runtime is not specified. +### OpenFaaS runtimes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29253) in GitLab 12.5. + +[OpenFaaS classic runtimes](https://github.com/openfaas/templates#templates-in-store) can be used with GitLab serverless. +Runtimes are specified using the pattern: `openfaas/classic/<template_name>`. The following +example shows how to define a function in `serverless.yml` using an OpenFaaS runtime: + +```yaml +hello: + source: ./hello + runtime: openfaas/classic/ruby + description: "Ruby function using OpenFaaS classic runtime" +``` + +`handler` is not needed for OpenFaaS functions. The location of the handler is defined +by the conventions of the runtime. + +See the [`ruby-openfaas-function`](https://gitlab.com/knative-examples/ruby-openfaas-function) +project for an example of a function using an OpenFaaS runtime. + +## Deploying functions + +> Introduced in GitLab 11.6. + You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. @@ -311,10 +388,49 @@ The sample function can now be triggered from any HTTP client using a simple `PO  +### Running functions locally + +Running a function locally is a good way to quickly verify behavior during development. + +Running functions locally requires: + +- Go 1.12 or newer installed. +- Docker Engine installed and running. +- `gitlabktl` installed using the Go package manager: + + ```shell + GO111MODULE=on go get gitlab.com/gitlab-org/gitlabktl + ``` + +To run a function locally: + +1. Navigate to the root of your GitLab serverless project. +1. Build your function into a Docker image: + + ```shell + gitlabktl serverless build + ``` + +1. Run your function in Docker: + + ```shell + docker run -itp 8080:8080 <your_function_name> + ``` + +1. Invoke your function: + + ```shell + curl http://localhost:8080 + ``` + ## Deploying Serverless applications > Introduced in GitLab 11.5. +Serverless applications are the building block of serverless functions. They are useful in scenarios where an existing +runtime does not meet the needs of an application, such as one written in a language that has no runtime available. Note +though that serverless applications should be stateless! + NOTE: **Note:** You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png Binary files differindex f813b60dcd9..f813b60dcd9 100755..100644 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png +++ b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png Binary files differindex 59da6874d14..59da6874d14 100755..100644 --- a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png +++ b/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png diff --git a/doc/user/project/img/time_tracking_example_v12_2.png b/doc/user/project/img/time_tracking_example_v12_2.png Binary files differnew file mode 100644 index 00000000000..31d8c490ed1 --- /dev/null +++ b/doc/user/project/img/time_tracking_example_v12_2.png diff --git a/doc/user/project/img/time_tracking_sidebar_v8_16.png b/doc/user/project/img/time_tracking_sidebar_v8_16.png Binary files differnew file mode 100644 index 00000000000..22124afed6f --- /dev/null +++ b/doc/user/project/img/time_tracking_sidebar_v8_16.png diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index f883e4474e2..94ab9d9195b 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -75,7 +75,5 @@ You also can:  ---- - You can also choose a different name for the project and a different namespace, if you have the privileges to do so. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 0aeca7f73ad..9b98c52c4b8 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -125,7 +125,7 @@ your GitHub repositories are listed. ## Mirroring and pipeline status sharing -Depending your GitLab tier, [project mirroring](../../../workflow/repository_mirroring.md) can be set up to keep +Depending your GitLab tier, [project mirroring](../repository/repository_mirroring.md) can be set up to keep your imported project in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 7ae288996da..c173d3d3e11 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -26,6 +26,7 @@ When you create a project in GitLab, you'll have access to a large number of from messing with history or pushing code without review - [Protected tags](protected_tags.md): Control over who has permission to create tags, and prevent accidental update or deletion + - [Repository mirroring](repository/repository_mirroring.md) - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Web IDE](web_ide/index.md) @@ -44,7 +45,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Review Apps](../../ci/review_apps/index.md): Live preview the results of the changes proposed in a merge request in a per-branch basis - [Labels](labels.md): Organize issues and merge requests by labels -- [Time Tracking](../../workflow/time_tracking.md): Track estimate time +- [Time Tracking](time_tracking.md): Track estimate time and time spent on the conclusion of an issue or merge request - [Milestones](milestones/index.md): Work towards a target date diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index ec43696fdee..62310dd9177 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -1,6 +1,6 @@ # Generic alerts integration **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. GitLab can accept alerts from any source via a generic webhook receiver. When you set up the generic alerts integration, a unique endpoint will @@ -16,7 +16,7 @@ authored by the GitLab Alert Bot. To set up the generic alerts integration: 1. Navigate to **Settings > Integrations** in a project. -1. Click on **Alert endpoint**. +1. Click on **Alerts endpoint**. 1. Toggle the **Active** alert setting. The `URL` and `Authorization Key` for the webhook configuration can be found there. ## Customizing the payload @@ -37,12 +37,12 @@ Example request: ```sh curl --request POST \ --data '{"title": "Incident title"}' \ - --header "Authorization: Bearer <autorization_key>" \ + --header "Authorization: Bearer <authorization_key>" \ --header "Content-Type: application/json" \ <url> ``` -The `<autorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). +The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). Example payload: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 50adb5993e5..c1e6f93de30 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -31,7 +31,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 team][slack-docs]. +docs on [Adding an app to your team](https://slack.com/help/articles/202035138). To enable GitLab's service for your Slack team: @@ -60,6 +60,5 @@ project, you would do: /gitlab gitlab-org/gitlab issue show 1001 ``` -[slack-docs]: https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team [slash commands]: ../../../integration/slash_commands.md [slack-manual]: slack_slash_commands.md diff --git a/doc/user/project/integrations/img/embed_metrics_issue_template.png b/doc/user/project/integrations/img/embed_metrics_issue_template.png Binary files differnew file mode 100644 index 00000000000..3c6a243e5c1 --- /dev/null +++ b/doc/user/project/integrations/img/embed_metrics_issue_template.png diff --git a/doc/user/project/integrations/img/grafana_panel_v12_5.png b/doc/user/project/integrations/img/grafana_panel_v12_5.png Binary files differnew file mode 100644 index 00000000000..18c17b910cd --- /dev/null +++ b/doc/user/project/integrations/img/grafana_panel_v12_5.png diff --git a/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png Binary files differnew file mode 100644 index 00000000000..fae62dd50df --- /dev/null +++ b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png diff --git a/doc/user/project/integrations/img/heatmap_panel_type.png b/doc/user/project/integrations/img/heatmap_panel_type.png Binary files differnew file mode 100644 index 00000000000..a2b3911ec68 --- /dev/null +++ b/doc/user/project/integrations/img/heatmap_panel_type.png diff --git a/doc/user/project/integrations/img/http_proxy_access_v12_5.png b/doc/user/project/integrations/img/http_proxy_access_v12_5.png Binary files differnew file mode 100644 index 00000000000..0036a916a12 --- /dev/null +++ b/doc/user/project/integrations/img/http_proxy_access_v12_5.png diff --git a/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png Binary files differnew file mode 100644 index 00000000000..5cba6fa9038 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png diff --git a/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png Binary files differnew file mode 100644 index 00000000000..6cabe4193bd --- /dev/null +++ b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png diff --git a/doc/user/project/integrations/img/select_query_variables_v12_5.png b/doc/user/project/integrations/img/select_query_variables_v12_5.png Binary files differnew file mode 100644 index 00000000000..23503577327 --- /dev/null +++ b/doc/user/project/integrations/img/select_query_variables_v12_5.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 6d2a0563ec1..874a1092b73 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -59,7 +59,7 @@ When connecting to **Jira Cloud**, which supports authentication via API token, > higher is required. > - GitLab 8.14 introduced a new way to integrate with Jira which greatly simplified > the configuration options you have to enter. If you are using an older version, -> [follow this documentation][jira-repo-old-docs]. +> [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/project_services/jira.md). > - In order to support Oracle's Access Manager, GitLab will send additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -205,4 +205,3 @@ authenticate with the Jira site. You will need to log in to your Jira instance and complete the CAPTCHA. [services-templates]: services_templates.md -[jira-repo-old-docs]: https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable/doc/project_services/jira.md diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index e385ee53636..315039f82b3 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -58,7 +58,7 @@ Click on the service links to see further configuration instructions and details ## Push hooks limit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31009) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services supported by `push_hooks` and `tag_push_hooks` events won't be executed. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index d7666d00e76..d3d4afefb59 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -117,7 +117,7 @@ You can view the performance dashboard for an environment by [clicking on the mo Custom metrics can be monitored by adding them on the monitoring dashboard page. Once saved, they will be displayed on the environment performance dashboard provided that either: -- A [connected Kubernetes cluster](../clusters/index.md#adding-and-removing-clusters) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration), or +- A [connected Kubernetes cluster](../clusters/add_remove_clusters.md) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration) - Prometheus is [manually configured](#manual-configuration-of-prometheus).  @@ -139,7 +139,7 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm - CI_ENVIRONMENT_SLUG - KUBE_NAMESPACE -To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. +To specify a variable in a query, enclose it in quotation marks with curly braces with a leading percent. For example: `"%{ci_environment_slug}"`. ### Defining custom dashboards per project @@ -211,11 +211,11 @@ The following tables outline the details of expected properties. | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | -| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be `area-chart` or `line-chart` | +| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be: `area-chart`, `line-chart` or `anomaly-chart`. | | `title` | string | yes | Heading for the panel. | | `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | -| `metrics` | array | yes | The metrics which should be displayed in the panel. | +| `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | **Metrics (`metrics`) properties:** @@ -231,20 +231,20 @@ The following tables outline the details of expected properties. The below panel types are supported in monitoring dashboards. -##### Area +##### Area or Line Chart -To add an area panel type to a dashboard, look at the following sample dashboard file: +To add an area chart panel type to a dashboard, look at the following sample dashboard file: ```yaml dashboard: 'Dashboard Title' panel_groups: - group: 'Group Title' panels: - - type: area-chart - title: "Chart Title" + - type: area-chart # or line-chart + title: 'Area Chart Title' y_label: "Y-Axis" metrics: - - id: 10 + - id: area_http_requests_total query_range: 'http_requests_total' label: "Metric of Ages" unit: "count" @@ -255,10 +255,52 @@ Note the following properties: | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | | type | string | no | Type of panel to be rendered. Optional for area panel types | -| query_range | yes | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | +| query_range | string | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) |  +##### Anomaly chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16530) in GitLab 12.5. + +To add an anomaly chart panel type to a dashboard, add add a panel with *exactly* 3 metrics. + +The first metric represents the current state, and the second and third metrics represent the upper and lower limit respectively: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - type: anomaly-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: anomaly_requests_normal + query_range: 'http_requests_total' + label: "# of Requests" + unit: "count" + metrics: + - id: anomaly_requests_upper_limit + query_range: 10000 + label: "Max # of requests" + unit: "count" + metrics: + - id: anomaly_requests_lower_limit + query_range: 2000 + label: "Min # of requests" + unit: "count" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | required | Must be `anomaly-chart` for anomaly panel types | +| query_range | yes | required | For anomaly panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) in every metric. | + + + ##### Single Stat To add a single stat panel type to a dashboard, look at the following sample dashboard file: @@ -286,6 +328,42 @@ Note the following properties:  +##### Heatmaps + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5. + +To add a heatmap panel type to a dashboard, look at the following sample dashboard file: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - title: "Heatmap" + type: "heatmap" + metrics: + - id: 10 + query: 'sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[60m])) by (status_code)' + unit: req/sec + label: "Status code" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | yes | Type of panel to be rendered. For heatmap panel types, set to `heatmap` | +| query_range | yes | yes | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | + + + +### View and edit the source file of a custom dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. + +When viewing a custom dashboard of a project, you can view the original +`.yml` file by clicking on **Edit dashboard** button. + ### Downloading data as CSV Data from Prometheus charts on the metrics dashboard can be downloaded as CSV. @@ -332,9 +410,12 @@ receivers: ... ``` +In order for GitLab to associate your alerts with an [environment](../../../ci/environments.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. + ### Taking action on incidents **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. Alerts can be used to trigger actions, like open an issue automatically (enabled by default since `12.1`). To configure the actions: @@ -355,6 +436,8 @@ Once enabled, an issue will be opened automatically when an alert is triggered w - Optional list of attached annotations extracted from `annotations/*` - Alert [GFM](../../markdown.md): GitLab Flavored Markdown from `annotations/gitlab_incident_markdown` +When GitLab receives a **Recovery Alert**, it will automatically close the associated issue. This action will be recorded as a system message on the issue indicated that it was closed automatically by the GitLab Alert bot. + To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. @@ -389,6 +472,8 @@ Prometheus server. ## Embedding metric charts within GitLab Flavored Markdown +### Embedding GitLab-managed Kubernetes metrics + > [Introduced][ce-29691] in GitLab 12.2. It is possible to display metrics charts within [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). @@ -414,9 +499,19 @@ The following requirements must be met for the metric to unfurl:  -### Embedding live Grafana charts +### Embedding metrics in issue templates + +It is also possible to embed either the default dashboard metrics or individual metrics in issue templates. For charts to render side-by-side, links to the entire metrics dashboard or individual metrics should be separated by either a comma or a space. + + + +### Embedding Grafana charts -It is also possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts within issues, as a [Direct Linked Rendered Image](https://grafana.com/docs/reference/sharing/#direct-link-rendered-image). +Grafana metrics can be embedded in [GitLab Flavored Markdown](../../markdown.md). + +#### Embedding charts via Grafana Rendered Images + +It is possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts in issues, as a [direct linked rendered image](https://grafana.com/docs/reference/sharing/#direct-link-rendered-image). The sharing dialog within Grafana provides the link, as highlighted below. @@ -435,6 +530,41 @@ This will render like so: <img src="https://dashboards.gitlab.com/render/d-solo/RZmbBr7mk/gitlab-triage?orgId=1&refresh=30s&var-env=gprd&var-environment=gprd&var-prometheus=prometheus-01-inf-gprd&var-prometheus_app=prometheus-app-01-inf-gprd&var-backend=All&var-type=All&var-stage=main&panelId=1247&width=1000&height=300"/> +#### Embedding charts via integration with Grafana HTTP API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31376) in GitLab 12.5. + +Each project can support integration with one Grafana instance. This configuration allows a user to copy a link to a panel in Grafana, then paste it into a GitLab markdown field. The chart will be rendered in the GitLab chart format. + +Prerequisites for embedding from a Grafana instance: + +1. The datasource must be a Prometheus instance. +1. The datasource must be proxyable, so the HTTP Access setting should be set to `Server`. + + + +##### Setting up the Grafana integration + +1. [Generate an Admin-level API Token in Grafana.](https://grafana.com/docs/http_api/auth/#create-api-token) +1. In your GitLab project, navigate to **Settings > Operations > Grafana Authentication**. +1. To enable the integration, check the "Active" checkbox. +1. For "Grafana URL", enter the base URL of the Grafana instance. +1. For "API Token", enter the Admin API Token you just generated. +1. Click **Save Changes**. + +##### Generating a link to a chart + +1. In Grafana, navigate to the dashboard you wish to embed a panel from. +  +1. In the upper-left corner of the page, select a specific value for each variable required for the queries in the chart. +  +1. In Grafana, click on a panel's title, then click **Share** to open the panel's sharing dialog to the **Link** tab. +1. If your Prometheus queries use Grafana's custom template variables, ensure that "Template variables" and "Current time range" options are toggled to **On**. Of Grafana global template variables, only `$__interval`, `$__from`, and `$__to` are currently supported. +  +1. Click **Copy** to copy the URL to the clipboard. +1. In GitLab, paste the URL into a markdown field and save. The chart will take a few moments to render. +  + ## Troubleshooting If the "No data found" screen continues to appear, it could be due to: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index d630956c109..93f6dbb0302 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -30,7 +30,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../clusters/index.md#getting-the-external-endpoint). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 83eac44666c..a1dcb105196 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -30,7 +30,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../clusters/index.md#getting-the-external-endpoint). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 103d50a94e8..403972941b2 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -287,7 +287,7 @@ Different issue board features are available in different [GitLab tiers](https:/ | Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists | |----------|--------------------------------|------------------------------|---------------------------|----------------| -| Core / Free | 1 | 1 | No | No | +| Core / Free | Multiple | 1 | No | No | | Starter / Bronze | Multiple | 1 | Yes | No | | Premium / Silver | Multiple | Multiple | Yes | Yes | | Ultimate / Gold | Multiple | Multiple | Yes | Yes | diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md new file mode 100644 index 00000000000..24775204c9f --- /dev/null +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -0,0 +1,42 @@ +# Associate a Zoom meeting with an issue + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16609) in GitLab 12.4. + +In order to communicate synchronously for incidents management, +GitLab allows to associate a Zoom meeting with an issue. +Once you start a Zoom call for a fire-fight, you need a way to +associate the conference call with an issue, so that your team +members can join swiftly without requesting a link. + +## Adding a zoom meeting to an issue + +To associate a zoom meeting with an issue, you can use GitLab's +[quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: + +```sh +/zoom https://zoom.us/j/123456789 +``` + +If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), +a system alert will notify you that the addition of the meeting URL was successful. +The issue's description will be automatically edited to include the Zoom link, and a button will +appear right under the issue's title. + + + +You are only allowed to attach a single Zoom meeting to an issue. If you attempt +to add a second Zoom meeting using the `/zoom` quick action, it won't work, you +need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. + +## Removing an existing Zoom meeting from an issue + +Similarly to adding a zoom meeting, you can remove it with a quick action: + +```sh +/remove_zoom +``` + +If you have at least [Reporter permissions](../../permissions.md), +a system alert will notify you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index fb7fdde7b94..b97bcd47f61 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -67,8 +67,8 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot | Milestone | Title of the issue milestone | | Weight | Issue weight | | Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | ## Limitations diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 169da7049a6..594f73dbfbe 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -22,24 +22,26 @@ For an overview, see the video [Design Management (GitLab 12.2)](https://www.you ## Requirements Design Management requires -[Large File Storage (LFS)](../../../workflow/lfs/manage_large_binaries_with_git_lfs.md) +[Large File Storage (LFS)](../../../administration/lfs/manage_large_binaries_with_git_lfs.md) to be enabled: - For GitLab.com, LFS is already enabled. - For self-managed instances, a GitLab administrator must have - [enabled LFS globally](../../../workflow/lfs/lfs_administration.md). + [enabled LFS globally](../../../administration/lfs/lfs_administration.md). - For both GitLab.com and self-managed instances: LFS must be enabled for the project itself. If enabled globally, LFS will be enabled by default to all projects. To enable LFS on the project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions** and enable **Git Large File Storage**. +Design Management requires that projects are using +[hashed storage](../../../administration/repository_storage_types.html#hashed-storage) +(the default storage type since v10.0). + ## Limitations - Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. The [`svg` extension is not yet supported](https://gitlab.com/gitlab-org/gitlab/issues/12771). - Design uploads are limited to 10 files at a time. -- Design Management is - [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab/issues/11090). - Design Management data [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/issues/13429) yet. - Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/issues/13426) @@ -112,12 +114,16 @@ viewed by browsing previous versions. ## Adding annotations to designs -When a design image is displayed, you can add annotations to it by clicking on -the image. A badge is added to the image and a form is displayed to start a new -discussion. For example: +When a design is uploaded, you can add annotations by clicking on +the image on the exact location you'd like to add the note to. +A badge is added to the image identifying the annotation, from +which you can start a new discussion:  -When submitted, the form saves a badge linked to the discussion on the image. Different discussions have different badge numbers. For example: +Different discussions have different badge numbers:  + +From GitLab 12.5 on, new annotations will be outputted to the issue activity, +so that everyone involved can participate in the discussion. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 240859651e2..b19d5dc1650 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -33,7 +33,7 @@ the icon and the date colored red. You can sort issues by those that are  -Due dates also appear in your [todos list](../../../workflow/todos.md). +Due dates also appear in your [todos list](../../todos.md).  diff --git a/doc/user/project/issues/img/issue_weight.png b/doc/user/project/issues/img/issue_weight.png Binary files differnew file mode 100644 index 00000000000..3800b5940b8 --- /dev/null +++ b/doc/user/project/issues/img/issue_weight.png diff --git a/doc/user/project/issues/img/select_all_designs_v12_4.png b/doc/user/project/issues/img/select_all_designs_v12_4.png Binary files differdeleted file mode 100644 index b08b04c1214..00000000000 --- a/doc/user/project/issues/img/select_all_designs_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/zoom-quickaction-button.png b/doc/user/project/issues/img/zoom-quickaction-button.png Binary files differindex d6d691b2267..c95a56b43e8 100644 --- a/doc/user/project/issues/img/zoom-quickaction-button.png +++ b/doc/user/project/issues/img/zoom-quickaction-button.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 01f4eb5b912..92da4235afa 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -41,7 +41,7 @@ after it is closed. #### 2. To Do -You can add issues to and remove issues from your [GitLab To-Do List](../../../workflow/todos.md). +You can add issues to and remove issues from your [GitLab To-Do List](../../todos.md). The button to do this has a different label depending on whether the issue is already on your To-Do List or not. If the issue is: @@ -83,9 +83,9 @@ Select a [milestone](../milestones/index.md) to attribute that issue to. #### 6. Time Tracking -Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../../../workflow/time_tracking.md). -You can add an [estimate of the time it will take](../../../workflow/time_tracking.md#estimates) -to resolve the issue, and also add [the time spent](../../../workflow/time_tracking.md#time-spent) +Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../time_tracking.md). +You can add an [estimate of the time it will take](../time_tracking.md#estimates) +to resolve the issue, and also add [the time spent](../time_tracking.md#time-spent) on the resolution of the issue. #### 7. Due date @@ -109,7 +109,7 @@ from which you can select **Create new label**. #### 9. Weight **(STARTER)** -[Assign a weight](../../../workflow/issue_weight.md) to an issue. +[Assign a weight](issue_weight.md) to an issue. Larger values are used to indicate more effort is required to complete the issue. Only positive values or zero are allowed. @@ -131,7 +131,7 @@ or were mentioned in the description or threads. #### 13. Notifications -Click on the icon to enable/disable [notifications](../../../workflow/notifications.md#issue--epics--merge-request-events) +Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) for the issue. This will automatically enable if you participate in the issue in any way. - **Enable**: If you are not a participant in the discussion on that issue, but @@ -162,7 +162,7 @@ allowing many formatting options. You can mention a user or a group present in your GitLab instance with `@username` or `@groupname` and they will be notified via todos and email, unless they have disabled all notifications in their profile settings. This is controlled in the -[notification settings](../../../workflow/notifications.md). +[notification settings](../../profile/notifications.md). Mentions for yourself (the current logged in user), will be highlighted in a different color, allowing you to easily see which comments involve you, helping you focus on @@ -257,4 +257,4 @@ You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove Attaching a [Zoom](https://zoom.us) call an issue results in a **Join Zoom meeting** button at the top of the issue, just under the header. - +Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md new file mode 100644 index 00000000000..4b8d2318e9b --- /dev/null +++ b/doc/user/project/issues/issue_weight.md @@ -0,0 +1,25 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' +--- + +# Issue weight **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/76) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. + +When you have a lot of issues, it can be hard to get an overview. +By adding a weight to each issue, you can get a better idea of how much time, +value or complexity a given issue has or will cost. + +You can set the weight of an issue during its creation, by simply changing the +value in the dropdown menu. You can set it to a non-negative integer +value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the +upper bound is essentially limitless). +You can remove weight from an issue +as well. + +This value will appear on the right sidebar of an individual issue, as well as +in the issues page next to a distinctive balance scale icon. + +As an added bonus, you can see the total sum of all issues on the milestone page. + + diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index cfd6d4eaf4b..d8356abdd1c 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -210,8 +210,8 @@ The following can be filtered by labels: ## Subscribing to labels From the project label list page and the group label list page, you can subscribe -to [notifications](../../workflow/notifications.md) of a given label, to alert you -that the label has been assigned to an epic, issue, and merge request. +to [notifications](../profile/notifications.md) of a given label, to alert you +that the label has been assigned to an epic, issue, or merge request.  diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 92681e741de..69bdfe10e3f 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -66,6 +66,18 @@ will scan your source code for code quality issues. The report will be saved as that you can later download and analyze. Due to implementation limitations we always take the latest Code Quality artifact available. +By default, report artifacts are not downloadable. If you need them downloadable on the +job details page, you can add `gl-code-quality-report.json` to the artifact paths like so: + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + artifacts: + paths: [gl-code-quality-report.json] +``` + The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI config, like so: ```yaml @@ -91,7 +103,7 @@ old job definitions are still maintained they have been deprecated and may be re in the next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. -For GitLab 11.5 and earlier, the job should look like: +For GitLab 11.5 and later, the job should look like: ```yaml code_quality: diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md new file mode 100644 index 00000000000..084ebf32a92 --- /dev/null +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -0,0 +1,156 @@ +--- +type: index, reference +--- + +# Creating merge requests + +Merge requests are the primary method of making changes to files in a GitLab project. +Changes are proposed by creating and submitting a merge request, which is then +[reviewed, and accepted (or rejected)](reviewing_and_managing_merge_requests.md), +all within GitLab. + +## Creating new merge requests + +You can start creating a new merge request by clicking the **New merge request** button +on the **Merge Requests** page in a project. Then you must choose the source project and +branch that contain your changes, and the target project and branch where you want to merge +the changes into. Click on **Compare branches and continue** to go to the next step +and start filling in the merge request details. + +When viewing the commits on a branch other than master in **Repository > Commits**, you +can click on the **Create merge request** button, and a new merge request will be started +using the current branch as the source, and `master` in the current project as the target. + +If you have recently pushed changes to GitLab, the **Create merge request** button will +also appear in the top right of the: + +- **Project** page. +- **Repository > Files** page. +- **Merge Requests** page. + +In this case, the merge request will use the most recent branch you pushed changes +to as the source branch, and `master` in the current project as the target. + +## Workflow for new merge requests + +On the **New Merge Request** page, you can start by filling in the title and description +for the merge request. If there are are already commits on the branch, the title will +be pre-filled with the first line of the first commit message, and the description will +be pre-filled with any additional lines in the commit message. The title is the only +field that is mandatory in all cases. + +From here, you can also: + +- Set the merge request as a [work in progress](work_in_progress_merge_requests.md). +- Select the [assignee](#assignee), or [assignees](#multiple-assignees-starter). **(STARTER)** +- Select a [milestone](../milestones/index.md). +- Select [labels](../labels.md). +- Add any [merge request dependencies](merge_request_dependencies.md). **(PREMIUM)** +- Select [approval options](merge_request_approvals.md). **(STARTER)** +- Verify the source and target branches are correct. +- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option. +- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option. +- If the merge request is from a fork, enable [Allow collaboration on merge requests across forks](allow_collaboration.md). + +Many of these can be set when pushing changes from the command line, with +[Git push options](../push_options.md). + +### Merge requests to close issues + +If the merge request is being created to resolve an issue, you can add a note in the +description which will set it to [automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) +when merged. + +If the issue is [confidential](../issues/confidential_issues.md), you may want to +use a different workflow for [merge requests for confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues), +to prevent confidential information from being exposed. + +## Assignee + +Choose an assignee to designate someone as the person responsible for the first +[review of the merge request](reviewing_and_managing_merge_requests.md). Open the +drop down box to search for the user you wish to assign, and the merge request will be +added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). + +### Multiple assignees **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). + +Multiple people often review merge requests at the same time. GitLab allows you to +have multiple assignees for merge requests to indicate everyone that is reviewing or +accountable for it. + + + +To assign multiple assignees to a merge request: + +1. From a merge request, expand the right sidebar and locate the **Assignees** section. +1. Click on **Edit** and from the dropdown menu, select as many users as you want + to assign the merge request to. + +Similarly, assignees are removed by deselecting them from the same dropdown menu. + +It's also possible to manage multiple assignees: + +- When creating a merge request. +- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +## Deleting the source branch + +When creating a merge request, select the "Delete source branch when merge +request accepted" option and the source branch will be deleted when the merge +request is merged. To make this option enabled by default for all new merge +requests, enable it in the [project's settings](../settings/index.md#merge-request-settings). + +This option is also visible in an existing merge request next to the merge +request button and can be selected/deselected before merging. It's only visible +to users with [Maintainer permissions](../../permissions.md) in the source project. + +If the user viewing the merge request does not have the correct permissions to +delete the source branch and the source branch is set for deletion, the merge +request widget will show the "Deletes source branch" text. + + + +## Create new merge requests by email + +_This feature needs [incoming email](../../../administration/incoming_email.md) +to be configured by a GitLab administrator to be available for CE/EE users, and +it's available on GitLab.com._ + +You can create a new merge request by sending an email to a user-specific email +address. The address can be obtained on the merge requests page by clicking on +a **Email a new merge request to this project** button. The subject will be +used as the source branch name for the new merge request and the target branch +will be the default branch for the project. The message body (if not empty) +will be used as the merge request description. You need +["Reply by email"](../../../administration/reply_by_email.md) enabled to use +this feature. If it's not enabled to your instance, you may ask your GitLab +administrator to do so. + +This is a private email address, generated just for you. **Keep it to yourself** +as anyone who gets ahold of it can create issues or merge requests as if they were you. +You can add this address to your contact list for easy access. + + + +_In GitLab 11.7, we updated the format of the generated email address. +However the older format is still supported, allowing existing aliases +or contacts to continue working._ + +### Adding patches when creating a merge request via e-mail + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22723) in GitLab 11.5. + +You can add commits to the merge request being created by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` will be considered patches and they will be processed +ordered by name. + +The combined size of the patches can be 2MB. + +If the source branch from the subject does not exist, it will be +created from the repository's HEAD or the specified target branch to +apply the patches. The target branch can be specified using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches will be applied on top of it. diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png Binary files differdeleted file mode 100644 index bbb131e86e9..00000000000 --- a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png Binary files differnew file mode 100644 index 00000000000..24c8c8f8c11 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png diff --git a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png b/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png Binary files differindex c704129685f..c704129685f 100755..100644 --- a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png +++ b/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2ab7c3fb15b..1ca8c882ac7 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,5 +1,5 @@ --- -type: index, reference, concepts +type: index, reference --- # Merge requests @@ -9,45 +9,9 @@ to source code that exist as commits on a given Git branch.  -## Overview - -A Merge Request (**MR**) is the basis of GitLab as a code collaboration -and version control platform. -It is as simple as the name implies: a _request_ to _merge_ one branch into another. - -With GitLab merge requests, you can: - -- Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching) -- [Review and discuss](../../discussions/index.md#threads) the proposed modifications inline -- Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project -- Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md) -- Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests) -- View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) -- [Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request -- Assign it to any registered user, and change the assignee how many times you need -- Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation -- Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md) -- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.md#time-tracking) -- [Resolve merge conflicts from the UI](#resolve-conflicts) -- Enable [fast-forward merge requests](#fast-forward-merge-requests) -- Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch -- [Create new merge requests by email](#create-new-merge-requests-by-email) -- [Allow collaboration](allow_collaboration.md) so members of the target project can push directly to the fork -- [Squash and merge](squash_and_merge.md) for a cleaner commit history - -With **[GitLab Enterprise Edition][ee]**, you can also: - -- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)** -- View the deployment process across projects with [Multi-Project Pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** -- Request [approvals](merge_request_approvals.md) from your managers **(STARTER)** -- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **(STARTER)** -- Manage the licenses of your dependencies with [License Compliance](../../application_security/license_compliance/index.md) **(ULTIMATE)** -- Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **(ULTIMATE)** -- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **(ULTIMATE)** -- Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **(ULTIMATE)** -- Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **(ULTIMATE)** -- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **(PREMIUM)** -- Specify merge order dependencies with [Merge Request Dependencies](#merge-request-dependencies-premium) **(PREMIUM)** +A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version +control platform. It is as simple as the name implies: a _request_ to _merge_ one +branch into another. ## Use cases @@ -58,8 +22,11 @@ A. Consider you are a software developer working in a team: 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **(STARTER)** 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../application_security/license_compliance/index.md) **(ULTIMATE)** -1. You request the [approval](#merge-request-approvals-starter) from your manager -1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) +1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** +1. Your manager: + 1. Pushes a commit with their final review + 1. [Approves the merge request](merge_request_approvals.md) **(STARTER)** + 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md) 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD 1. Your implementations were successfully shipped to your customer @@ -71,547 +38,112 @@ B. Consider you're a web developer writing a webpage for your company's website: 1. You request your web designers for their implementation 1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) -1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production - -## Merge requests per project - -View all the merge requests within a project by navigating to **Project > Merge Requests**. - -When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project). - - - -## Merge requests per group - -View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. - -You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here. - - - -## Deleting the source branch - -When creating a merge request, select the "Delete source branch when merge -request accepted" option and the source branch will be deleted when the merge -request is merged. - -This option is also visible in an existing merge request next to the merge -request button and can be selected/deselected before merging. It's only visible -to users with [Maintainer permissions](../../permissions.md) in the source project. - -If the user viewing the merge request does not have the correct permissions to -delete the source branch and the source branch is set for deletion, the merge -request widget will show the "Deletes source branch" text. - - - -## Allow collaboration on merge requests across forks - -When a user opens a merge request from a fork, they are given the option to allow -upstream maintainers to collaborate with them on the source branch. This allows -the maintainers of the upstream project to make small fixes or rebase branches -before merging, reducing the back and forth of accepting community contributions. - -[Learn more about allowing upstream members to push to forks.](allow_collaboration.md) +1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production + +## Creating merge requests + +While making changes to files in the `master` branch of a repository is possible, it is not +the common workflow. In most cases, a user will make changes in a [branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching), +then [create a merge request](creating_merge_requests.md) to request that the changes +be merged into another branch (often the `master` branch). + +It is then [reviewed](#reviewing-and-managing-merge-requests), possibly updated after +discussions and suggestions, and finally approved and merged into the target branch. +Creating and reviewing merge requests is one of the most fundamental parts of working +with GitLab. + +When [creating merge requests](creating_merge_requests.md), there are a number of features +to be aware of: + +| Feature | Description | +|-----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Adding patches when creating a merge request via e-mail](creating_merge_requests.md#adding-patches-when-creating-a-merge-request-via-e-mail) | Add commits to a merge request created by e-mail, by adding patches as e-mail attachments. | +| [Allow collaboration on merge requests across forks](allow_collaboration.md) | Allows the maintainers of an upstream project to collaborate on a fork, to make fixes or rebase branches before merging, reducing the back and forth of accepting community contributions. | +| [Assignee](creating_merge_requests.md#assignee) | Add an assignee to indicate who is reviewing or accountable for it. | +| [Automatic issue closing](../../project/issues/managing_issues.md#closing-issues-automatically) | Set a merge request to close defined issues automatically as soon as it is merged. | +| [Create new merge requests by email](creating_merge_requests.md#create-new-merge-requests-by-email) | Create new merge requests by sending an email to a user-specific email address. | +| [Deleting the source branch](creating_merge_requests.md#deleting-the-source-branch) | Select the "Delete source branch when merge request accepted" option and the source branch will be deleted when the merge request is merged. | +| [Git push options](../push_options.md) | Use Git push options to create or update merge requests when pushing changes to GitLab with Git, without needing to use the GitLab interface. | +| [Labels](../../project/labels.md) | Organize your issues and merge requests consistently throughout the project. | +| [Merge request approvals](merge_request_approvals.md) **(STARTER)** | Set the number of necessary approvals and predefine a list of approvers that will need to approve every merge request in a project. | +| [Merge Request dependencies](merge_request_dependencies.md) **(PREMIUM)** | Specify that a merge request depends on other merge requests, enforcing a desired order of merging. | +| [Merge Requests for Confidential Issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) | Create merge requests to resolve confidential issues for preventing leakage or early release of sensitive data through regular merge requests. | +| [Milestones](../../project/milestones/index.md) | Track merge requests to achieve a broader goal in a certain period of time. | +| [Multiple assignees](creating_merge_requests.md#multiple-assignees-starter) **(STARTER)** | Have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it. | +| [Squash and merge](squash_and_merge.md) | Squash all changes present in a merge request into a single commit when merging, to allow for a neater commit history. | +| [Work In Progress merge requests](work_in_progress_merge_requests.md) | Prevent the merge request from being merged before it's ready | + +## Reviewing and managing merge requests + +Once a merge request has been [created](#creating-merge-requests) and submitted, there +are many powerful features that you can use during the review process to make sure only +the changes you want are merged into the repository. + +For managers and administrators, it is also important to be able to view and manage +all the merge requests in a group or project. When [reviewing or managing merge requests](reviewing_and_managing_merge_requests.md), +there are a number of features to be aware of: + +| Feature | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | +| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | +| [Commenting on any file line in merge requests](reviewing_and_managing_merge_requests.md#commenting-on-any-file-line-in-merge-requests) | Make comments directly on the exact line of a file you want to talk about. | +| [Discuss changes in threads in merge requests reviews](../../discussions/index.md) | Keep track of the progress during a code review by making and resolving comments. | +| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | +| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | +| [Ignore whitespace changes in Merge Request diff view](reviewing_and_managing_merge_requests.md#ignore-whitespace-changes-in-Merge-Request-diff-view) | Hide whitespace changes from the diff view for a to focus on more important changes. | +| [Incrementally expand merge request diffs](reviewing_and_managing_merge_requests.md#incrementally-expand-merge-request-diffs) | View the content directly above or below a change, to better understand the context of that change. | +| [Live preview with Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps) | Live preview the changes when Review Apps are configured for your project | +| [Merge request diff file navigation](reviewing_and_managing_merge_requests.md#merge-request-diff-file-navigation) | Quickly jump to any changed file within the diff view. | +| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | +| [Merge when pipeline succeeds](merge_when_pipeline_succeeds.md) | Set a merge request that looks ready to merge to merge automatically when CI pipeline succeeds. | +| [Perform a Review](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)** | Start a review in order to create multiple comments on a diff and publish them once you're ready. | +| [Pipeline status in merge requests](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests) | If using [GitLab CI/CD](../../../ci/README.md), see pre and post-merge pipelines information, and which deployments are in progress. | +| [Post-merge pipeline status](reviewing_and_managing_merge_requests.md#post-merge-pipeline-status) | When a merge request is merged, see the post-merge pipeline status of the branch the merge request was merged into. | +| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | +| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | +| [Semi-linear history merge requests](reviewing_and_managing_merge_requests.md#semi-linear-history-merge-requests) | Enable semi-linear history merge requests as another security layer to guarantee the pipeline is passing in the target branch | +| [Suggest changes](../../discussions/index.md#suggest-changes) | Add suggestions to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. | +| [Time Tracking](../time_tracking.md#time-tracking) | Add a time estimation and the time spent with that merge request. | +| [View changes between file versions](reviewing_and_managing_merge_requests.md#view-changes-between-file-versions) | View what will be changed when a merge request is merged. | +| [View group merge requests](reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) | List and view the merge requests within a group. | +| [View project merge requests](reviewing_and_managing_merge_requests.md#view-project-merge-requests) | List and view the merge requests within a project. | + +## Testing and reports in merge requests + +GitLab has the ability to test the changes included in a merge request, and can display +or link to useful information directly in the merge request page: + +| Feature | Description | +|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | +| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | +| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | +| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | +| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | +| [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | +| [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | +| [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) | View the status of pipelines within the merge request, including the deployment process. | + +### Security Reports **(ULTIMATE)** + +In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), +generated by scanning and reporting any vulnerabilities found in your project: + +| Feature | Description | +|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| +| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | +| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | +| [License Compliance](../../application_security/license_compliance/index.md) | Manage the licenses of your dependencies. | +| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | ## Authorization for merge requests There are two main ways to have a merge request flow with GitLab: -1. Working with [protected branches][] in a single repository +1. Working with [protected branches](../protected_branches.md) in a single repository 1. Working with forks of an authoritative project [Learn more about the authorization for merge requests.](authorization_for_merge_requests.md) - -## Cherry-pick changes - -Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button -in a merged merge requests or a commit. - -[Learn more about cherry-picking changes.](cherry_pick_changes.md) - -## Semi-linear history merge requests - -A merge commit is created for every merge, but the branch is only merged if -a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build will also succeed after merging. - -Navigate to a project's settings, select the **Merge commit with semi-linear -history** option under **Merge Requests: Merge method** and save your changes. - -## Fast-forward merge requests - -If you prefer a linear Git history and a way to accept merge requests without -creating merge commits, you can configure this on a per-project basis. - -[Read more about fast-forward merge requests.](fast_forward_merge.md) - -## Merge when pipeline succeeds - -When reviewing a merge request that looks ready to merge but still has one or -more CI jobs running, you can set it to be merged automatically when CI -pipeline succeeds. This way, you don't have to wait for the pipeline to finish -and remember to merge the request manually. - -[Learn more about merging when pipeline succeeds.](merge_when_pipeline_succeeds.md) - -## Resolve threads in merge requests reviews - -Keep track of the progress during a code review with resolving comments. -Resolving comments prevents you from forgetting to address feedback and lets -you hide threads that are no longer relevant. - -[Read more about resolving threads in merge requests reviews.](../../discussions/index.md) - -## View changes between file versions - -The **Changes** tab of a merge request shows the changes to files between branches or -commits. This view of changes to a file is also known as a **diff**. By default, the diff view -compares the file in the merge request branch and the file in the target branch. - -The diff view includes the following: - -- The file's name and path. -- The number of lines added and deleted. -- Buttons for the following options: - - Toggle comments for this file; useful for inline reviews. - - Edit the file in the merge request's branch. - - Show full file, in case you want to look at the changes in context with the rest of the file. - - View file at the current commit. - - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). -- The changed lines, with the specific changes highlighted. - - - -## Commenting on any file line in merge requests - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. - -GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. - - - -## Perform a Review **(PREMIUM)** - -Start a review in order to create multiple comments on a diff and publish them once you're ready. -Starting a review allows you to get all your thoughts in order and ensure you haven't missed anything -before submitting all your comments. - -[Learn more about Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) - -## Squash and merge - -GitLab allows you to squash all changes present in a merge request into a single -commit when merging, to allow for a neater commit history. - -[Learn more about squash and merge.](squash_and_merge.md) - -## Suggest changes - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/18008) in GitLab 11.6. - -As a reviewer, you can add suggestions to change the content in -merge request threads, and users with appropriate [permission](../../permissions.md) -can easily apply them to the codebase directly from the UI. Read -through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes) -to learn more. - -## Multiple assignees **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) -in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). - -Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it. - - - -To assign multiple assignees to a merge request: - -1. From a merge request, expand the right sidebar and locate the **Assignees** section. -1. Click on **Edit** and from the dropdown menu, select as many users as you want - to assign the merge request to. - -Similarly, assignees are removed by deselecting them from the same dropdown menu. - -It's also possible to manage multiple assignees: - -- When creating a merge request. -- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). - -## Resolve conflicts - -When a merge request has conflicts, GitLab may provide the option to resolve -those conflicts in the GitLab UI. - -[Learn more about resolving merge conflicts in the UI.](resolve_conflicts.md) - -## Create new merge requests by email - -_This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available for CE/EE users, and -it's available on GitLab.com._ - -You can create a new merge request by sending an email to a user-specific email -address. The address can be obtained on the merge requests page by clicking on -a **Email a new merge request to this project** button. The subject will be -used as the source branch name for the new merge request and the target branch -will be the default branch for the project. The message body (if not empty) -will be used as the merge request description. You need -["Reply by email"](../../../administration/reply_by_email.md) enabled to use -this feature. If it's not enabled to your instance, you may ask your GitLab -administrator to do so. - -This is a private email address, generated just for you. **Keep it to yourself** -as anyone who gets ahold of it can create issues or merge requests as if they were you. -You can add this address to your contact list for easy access. - - - -_In GitLab 11.7, we updated the format of the generated email address. -However the older format is still supported, allowing existing aliases -or contacts to continue working._ - -### Adding patches when creating a merge request via e-mail - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22723) in GitLab 11.5. - -You can add commits to the merge request being created by adding -patches as attachments to the email. All attachments with a filename -ending in `.patch` will be considered patches and they will be processed -ordered by name. - -The combined size of the patches can be 2MB. - -If the source branch from the subject does not exist, it will be -created from the repository's HEAD or the specified target branch to -apply the patches. The target branch can be specified using the -[`/target_branch` quick action](../quick_actions.md). If the source -branch already exists, the patches will be applied on top of it. - -## Use Git push options with merge requests - -Use [Git push options](../push_options.md) to create or update merge requests when -pushing changes to GitLab with Git, without needing to use the GitLab interface. - -## Find the merge request that introduced a change - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2383) in GitLab 10.5. - -When viewing the commit details page, GitLab will link to the merge request (or -merge requests, if it's in more than one) containing that commit. - -This only applies to commits that are in the most recent version of a merge -request - if a commit was in a merge request, then rebased out of that merge -request, they will not be linked. - -[Read more about merge request versions](versions.md) - -## Revert changes - -GitLab implements Git's powerful feature to revert any commit with introducing -a **Revert** button in merge requests and commit details. - -[Learn more about reverting changes in the UI](revert_changes.md) - -## Merge requests versions - -Every time you push to a branch that is tied to a merge request, a new version -of merge request diff is created. When you visit a merge request that contains -more than one pushes, you can select and compare the versions of those merge -request diffs. - -[Read more about merge request versions](versions.md) - -## Work In Progress merge requests - -To prevent merge requests from accidentally being accepted before they're -completely ready, GitLab blocks the "Accept" button for merge requests that -have been marked as a **Work In Progress**. - -[Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md) - -## Merge Requests for Confidential Issues - -Create [merge requests to resolve confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) -for preventing leakage or early release of sensitive data through regular merge requests. - -## Merge request approvals **(STARTER)** - -> Included in [GitLab Starter](https://about.gitlab.com/product/). - -If you want to make sure every merge request is approved by one or more people, -you can enforce this workflow by using merge request approvals. Merge request -approvals allow you to set the number of necessary approvals and predefine a -list of approvers that will need to approve every merge request in a project. - -[Read more about merge request approvals.](merge_request_approvals.md) - -## Code Quality **(STARTER)** - -> Introduced in [GitLab Starter](https://about.gitlab.com/product/) 9.3. - -If you are using [GitLab CI][ci], you can analyze your source code quality using -the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab -can show the Code Climate report right in the merge request widget area. - -[Read more about Code Quality reports.](code_quality.md) - -## Metrics Reports **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9788) in [GitLab Premium](https://about.gitlab.com/product/) 11.10. -Requires GitLab Runner 11.10 and above. - -If you are using [GitLab CI][ci], you can configure your job to output custom -metrics and GitLab will display the Metrics Report on the merge request so -that it's fast and easy to identify changes to important metrics. - -[Read more about Metrics Report](../../../ci/metrics_reports.md). - -## Browser Performance Testing **(PREMIUM)** - -> Introduced in [GitLab Premium](https://about.gitlab.com/product/) 10.3. - -If your application offers a web interface and you are using [GitLab CI/CD][ci], you can quickly determine the performance impact of pending code changes. GitLab uses [Sitespeed.io][sitespeed], a free and open source tool for measuring the performance of web sites, to analyze the performance of specific pages. - -GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the difference in overall performance scores between the source and target branches. - -[Read more about Browser Performance Testing.](browser_performance_testing.md) - -## Merge Request Dependencies **(PREMIUM)** - -> Introduced in [GitLab Premium](https://about.gitlab.com/product/) 12.2. - -A single logical change may be split across several merge requests, across -several projects. When this happens, the order in which MRs are merged is -important. - -GitLab allows you to specify that a merge request depends on other MRs. With -this relationship in place, the merge request cannot be merged until all of its -dependencies have also been merged, helping to maintain the consistency of a -single logical change. - -[Read more about merge request dependencies.](merge_request_dependencies.md) - -## Security reports **(ULTIMATE)** - -GitLab can scan and report any vulnerabilities found in your project. - -[Read more about security reports.](../../application_security/index.md) - -## JUnit test reports - -Configure your CI jobs to use JUnit test reports, and let GitLab display a report -on the merge request so that it’s easier and faster to identify the failure -without having to check the entire job log. - -[Read more about JUnit test reports](../../../ci/junit_test_reports.md). - -## Merge request diff file navigation - -When reviewing changes in the **Changes** tab the diff can be navigated using -the file tree or file list. As you scroll through large diffs with many -changes, you can quickly jump to any changed file using the file tree or file -list. - - - -### Incrementally expand merge request diffs - -By default, the diff shows only the parts of a file which are changed. -To view more unchanged lines above or below a change click on the -**Expand up** or **Expand down** icons. You can also click on **Show all lines** -to expand the entire file. - - - -## Ignore whitespace changes in Merge Request diff view - -If you click the **Hide whitespace changes** button, you can see the diff -without whitespace changes (if there are any). This is also working when on a -specific commit page. - - - ->**Tip:** -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - -## Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project, -you can preview the changes submitted to a feature-branch through a merge request -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. - -With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../ci/review_apps/index.md). - -## Pipelines for merge requests - -When a developer updates a merge request, a pipeline should quickly report back -its result to the developer, but often pipelines take long time to complete -because general branch pipelines contain unnecessary jobs from the merge request standpoint. -You can customize a specific pipeline structure for merge requests in order to -speed the cycle up by running only important jobs. - -Learn more about [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md). - -## Pipeline status in merge requests - -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you will be able to see: - -- Both pre and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If there's an [environment](../../../ci/environments.md) and the application is -successfully deployed to it, the deployed environment and the link to the -Review App will be shown as well. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the master branch and then triggers a deployment to the staging -environment. - -Deployments that are ongoing will be shown, as well as the deploying/deployed state -for environments. If it's the first time the branch is deployed, the link -will return a `404` error until done. During the deployment, the stop button will -be disabled. If the pipeline fails to deploy, the deployment info will be hidden. - - - -For more information, [read about pipelines](../../../ci/pipelines.md). - -## Bulk editing merge requests - -Find out about [bulk editing merge requests](../../project/bulk_editing.md). - -## Troubleshooting - -Sometimes things don't go as expected in a merge request, here are some -troubleshooting steps. - -### Merge request cannot retrieve the pipeline status - -This can occur if Sidekiq doesn't pick up the changes fast enough. - -#### Sidekiq - -Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status will update automatically. - -#### Bug - -Merge Request pipeline statuses can't be retrieved when the following occurs: - -1. A Merge Request is created -1. The Merge Request is closed -1. Changes are made in the project -1. The Merge Request is reopened - -To enable the pipeline status to be properly retrieved, close and reopen the -Merge Request again. - -## Tips - -Here are some tips that will help you be more efficient with merge requests in -the command line. - -> **Note:** -This section might move in its own document in the future. - -### Checkout merge requests locally - -A merge request contains all the history from a repository, plus the additional -commits added to the branch associated with the merge request. Here's a few -tricks to checkout a merge request locally. - -Please note that you can checkout a merge request locally even if the source -project is a fork (even a private fork) of the target project. - -#### Checkout locally by adding a Git alias - -Add the following alias to your `~/.gitconfig`: - -``` -[alias] - mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - -``` - -Now you can check out a particular merge request from any repository and any -remote. For example, to check out the merge request with ID 5 as shown in GitLab -from the `origin` remote, do: - -``` -git mr origin 5 -``` - -This will fetch the merge request into a local `mr-origin-5` branch and check -it out. - -#### Checkout locally by modifying `.git/config` for a given repository - -Locate the section for your GitLab remote in the `.git/config` file. It looks -like this: - -``` -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* -``` - -You can open the file with: - -``` -git config -e -``` - -Now add the following line to the above section: - -``` -fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -In the end, it should look like this: - -``` -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* - fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -Now you can fetch all the merge requests: - -``` -git fetch origin - -... -From https://gitlab.com/gitlab-org/gitlab-foss.git - * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 - * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 -... -``` - -And to check out a particular merge request: - -``` -git checkout origin/merge-requests/1 -``` - -All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. - -[protected branches]: ../protected_branches.md -[ci]: ../../../ci/README.md -[cc]: https://codeclimate.com/ -[cd]: https://hub.docker.com/r/codeclimate/codeclimate/ -[sitespeed]: https://www.sitespeed.io -[sitespeed-container]: https://hub.docker.com/r/sitespeedio/sitespeed.io/ -[ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition" diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 2aa92ba2316..76c348eb93e 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -75,9 +75,9 @@ request approval rules: 1. Click **Add approvers** to create a new approval rule. 1. Just like in [GitLab Starter](#editing-approvals), select the approval members and approvals required. 1. Give the approval rule a name that describes the set of approvers selected. -1. Click **Add approvers** to submit the new rule. +1. Click **Add approval rule** to submit the new rule. -  +  ## Multiple approval rules **(PREMIUM)** @@ -219,8 +219,6 @@ and the project level approvers are changed after a merge request is created, the merge request retains the previous approvers. However, the approvers can be changed by [editing the merge request](#overriding-the-merge-request-approvals-default-settings). ---- - The default approval settings can now be overridden when creating a [merge request](index.md) or by editing it after it's been created: diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index dab2184448a..6630179ea47 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -85,3 +85,8 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> + +## Use it from the command line + +You can use [Push Options](../push_options.md) to trigger this feature when +pushing. diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md new file mode 100644 index 00000000000..f693b0b1e72 --- /dev/null +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -0,0 +1,251 @@ +--- +type: index, reference +--- + +# Reviewing and managing merge requests + +Merge requests are the primary method of making changes to files in a GitLab project. +Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), +which is then reviewed, and accepted (or rejected). + +## View project merge requests + +View all the merge requests within a project by navigating to **Project > Merge Requests**. + +When you access your project's merge requests, GitLab will present them in a list, +and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project). + + + +## View merge requests for all projects in a group + +View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. + +You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here. + + + +## Semi-linear history merge requests + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build will also succeed after merging. + +Navigate to a project's settings, select the **Merge commit with semi-linear history** +option under **Merge Requests: Merge method** and save your changes. + +## View changes between file versions + +The **Changes** tab, below the main merge request details and next to the discussion tab, +shows the changes to files between branches or commits. This view of changes to a +file is also known as a **diff**. By default, the diff view compares the file in the +merge request branch and the file in the target branch. + +The diff view includes the following: + +- The file's name and path. +- The number of lines added and deleted. +- Buttons for the following options: + - Toggle comments for this file; useful for inline reviews. + - Edit the file in the merge request's branch. + - Show full file, in case you want to look at the changes in context with the rest of the file. + - View file at the current commit. + - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). +- The changed lines, with the specific changes highlighted. + + + +### Merge request diff file navigation + +When reviewing changes in the **Changes** tab the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list. + + + +### Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change click on the +**Expand up** or **Expand down** icons. You can also click on **Show all lines** +to expand the entire file. + + + +### Ignore whitespace changes in Merge Request diff view + +If you click the **Hide whitespace changes** button, you can see the diff +without whitespace changes (if there are any). This is also working when on a +specific commit page. + + + +>**Tip:** +You can append `?w=1` while on the diffs page of a merge request to ignore any +whitespace changes. + +## Commenting on any file line in merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. + +GitLab provides a way of leaving comments in any part of the file being changed +in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. + + + +## Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project, +you can preview the changes submitted to a feature-branch through a merge request +in a per-branch basis. No need to checkout the branch, install and preview locally; +all your changes will be available to preview by anyone with the Review Apps link. + +With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). + +## Pipeline status in merge requests + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +you will be able to see: + +- Both pre and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If there's an [environment](../../../ci/environments.md) and the application is +successfully deployed to it, the deployed environment and the link to the +Review App will be shown as well. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the master branch and then triggers a deployment to the staging +environment. + +Deployments that are ongoing will be shown, as well as the deploying/deployed state +for environments. If it's the first time the branch is deployed, the link +will return a `404` error until done. During the deployment, the stop button will +be disabled. If the pipeline fails to deploy, the deployment info will be hidden. + + + +For more information, [read about pipelines](../../../ci/pipelines.md). + +## Troubleshooting + +Sometimes things don't go as expected in a merge request, here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur if Sidekiq doesn't pick up the changes fast enough. + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status will update automatically. + +#### Bug + +Merge Request pipeline statuses can't be retrieved when the following occurs: + +1. A Merge Request is created +1. The Merge Request is closed +1. Changes are made in the project +1. The Merge Request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +Merge Request again. + +## Tips + +Here are some tips that will help you be more efficient with merge requests in +the command line. + +> **Note:** +This section might move in its own document in the future. + +### Checkout merge requests locally + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +tricks to checkout a merge request locally. + +Please note that you can checkout a merge request locally even if the source +project is a fork (even a private fork) of the target project. + +#### Checkout locally by adding a Git alias + +Add the following alias to your `~/.gitconfig`: + +``` +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `origin` remote, do: + +``` +git mr origin 5 +``` + +This will fetch the merge request into a local `mr-origin-5` branch and check +it out. + +#### Checkout locally by modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +You can open the file with: + +``` +git config -e +``` + +Now add the following line to the above section: + +``` +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +In the end, it should look like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +``` +git fetch origin + +... +From https://gitlab.com/gitlab-org/gitlab-foss.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +And to check out a particular merge request: + +``` +git checkout origin/merge-requests/1 +``` + +All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index fbe216c3aed..ffd0efb365a 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -35,6 +35,17 @@ changes appears as a system note.  +## Find the merge request that introduced a change + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2383) in GitLab 10.5. + +When viewing the commit details page, GitLab will link to the merge request (or +merge requests, if it's in more than one) containing that commit. + +This only applies to commits that are in the most recent version of a merge +request - if a commit was in a merge request, then rebased out of that merge +request, they will not be linked. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 105854ccd33..21a4e3d8ead 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -12,23 +12,21 @@ Milestones allow you to organize issues and merge requests into a cohesive group ## Milestones as Agile sprints -Milestones can be used as Agile sprints. -Set the milestone start date and due date to represent -the start and end of your Agile sprint. -Set the milestone title to the name of your Agile sprint, -such as `November 2018 sprint`. -Add an issue to your Agile sprint by associating -the milestone to the issue. +Milestones can be used as Agile sprints so that you can track all issues and merge requests related to a particular sprint. To do so: + +1. Set the milestone start date and due date to represent the start and end of your Agile sprint. +1. Set the milestone title to the name of your Agile sprint, such as `November 2018 sprint`. +1. Add an issue to your Agile sprint by associating the desired milestone from the issue's right-hand sidebar. ## Milestones as releases -Milestones can be used as releases. -Set the milestone due date to represent the release date of your release. -(And leave the milestone start date blank.) -Set the milestone title to the version of your release, -such as `Version 9.4`. -Add an issue to your release by associating -the milestone to the issue. +Similarily, milestones can be used as releases. To do so: + +1. Set the milestone due date to represent the release date of your release and leave the milestone start date blank. +1. Set the milestone title to the version of your release, such as `Version 9.4`. +1. Add an issue to your release by associating the desired milestone from the issue's right-hand sidebar. + +Additionally, you can integrate milestones with GitLab's [Releases feature](../releases/index.md#releases-associated-with-milestones). ## Project milestones and group milestones @@ -103,30 +101,18 @@ When filtering by milestone, in addition to choosing a specific project mileston ## Milestone view -Not all features in the project milestone view are available in the group milestone view. This table summarizes the differences: - -| Feature | Project milestone view | Group milestone view | -|--------------------------------------|:----------------------:|:--------------------:| -| Title an description | ✓ | ✓ | -| Issues assigned to milestone | ✓ | | -| Merge requests assigned to milestone | ✓ | | -| Participants and labels used | ✓ | | -| Percentage complete | ✓ | ✓ | -| Start date and due date | ✓ | ✓ | -| Total issue time spent | ✓ | ✓ | -| Total issue weight | ✓ | | -| Burndown chart **[STARTER}** | ✓ | ✓ | - The milestone view shows the title and description. -### Project milestone features - -These features are only available for project milestones and not group milestones. +There are also tabs below these that show the following: -- Issues assigned to the milestone are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. -- Merge requests assigned to the milestone are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. -- Participants and labels that are used in issues and merge requests that have the milestone assigned are displayed. -- [Burndown chart](#project-burndown-charts-starter). +- Issues + Shows all issues assigned to the milestone. These are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. +- Merge requests + Shows all merge requests assigned to the milestone. These are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. +- Participants + Shows all assignees of issues assigned to the milestone. +- Labels + Shows all labels that are used in issues assigned to the milestone. ### Project Burndown Charts **(STARTER)** @@ -144,9 +130,8 @@ The milestone sidebar on the milestone view shows the following: - Percentage complete, which is calculated as number of closed issues divided by total number of issues. - The start date and due date. -- The total time spent on all issues that have the milestone assigned. - -For project milestones only, the milestone sidebar shows the total issue weight of all issues that have the milestone assigned. +- The total time spent on all issues assigned to the milestone. +- The total issue weight of all issues assigned to the milestone.  diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 1b319c5641c..04eda026bc3 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -6,7 +6,7 @@ Error tracking allows developers to easily discover and view the errors that the ## Sentry error tracking -[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab itself. +[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab. ### Deploying Sentry @@ -20,6 +20,7 @@ You will need at least Maintainer [permissions](../../permissions.md) to enable GitLab provides an easy way to connect Sentry to your project: 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. +1. [Create](https://docs.sentry.io/guides/integrate-frontend/create-new-project/) a new Sentry project. For each GitLab project that you want to integrate, we recommend that you create a new Sentry project. 1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project. Make sure to give the token at least the following scopes: `event:read` and `project:read`. 1. Navigate to your project’s **Settings > Operations**. @@ -31,11 +32,27 @@ GitLab provides an easy way to connect Sentry to your project: 1. Click **Save changes** for the changes to take effect. 1. You can now visit **Operations > Error Tracking** in your project's sidebar to [view a list](#error-tracking-list) of Sentry errors. +### Enabling Gitlab issues links + +You may also want to enable Sentry's GitLab integration by following the steps in the [Sentry documentation](https://docs.sentry.io/workflow/integrations/global-integrations/#gitlab) + ## Error Tracking List NOTE: **Note:** You will need at least Reporter [permissions](../../permissions.md) to view the Error Tracking list. The Error Tracking list may be found at **Operations > Error Tracking** in your project's sidebar. +Errors can be filtered by title.  + +## Error Details + +From error list, users can navigate to the error details page by clicking the title of any error. + +This page has: + +- A link to Sentry issue. +- A full stack trace along with other details. + + diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 08df92959c3..c05f8fa8bc4 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -81,7 +81,14 @@ NOTE: **NOTE** We'd highly recommend you to use the [Environment](../../../ci/environments.md) feature in order to quickly assess which flag is enabled per environment. -## Rollout strategy +## Feature Flag strategies + +GitLab Feature Flag adopts [Unleash](https://unleash.github.io) +as the feature flag engine. In unleash, there is a concept of rulesets for granular feature flag controls, +called [strategies](https://unleash.github.io/docs/activation_strategy). +Supported strategies for GitLab Feature Flags are described below. + +### Rollout strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. @@ -91,13 +98,13 @@ The status of an environment spec ultimately determines whether or not a feature For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy. However, a feature will be enabled for 50% of logged-in users if the matching environment spec has an enabled status along with a **Percent rollout (logged in users)** strategy set to 50%. -### All users +#### All users Enables the feature for all users. It is implemented using the Unleash [`default`](https://unleash.github.io/docs/activation_strategy#default) activation strategy. -### Percent rollout (logged in users) +#### Percent rollout (logged in users) Enables the feature for a percentage of authenticated users. It is implemented using the Unleash @@ -112,7 +119,7 @@ CAUTION: **Caution:** If this strategy is selected, then the Unleash client **must** be given a user ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. -## Target users +### Target users strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. @@ -134,7 +141,7 @@ In order to use Feature Flags, you need to first [get the access credentials](#configuring-feature-flags) from GitLab and then prepare your application and hook it with a [client library](#client-libraries). -### Configuring Feature Flags +## Configuring Feature Flags To get the access credentials that your application will need to talk to GitLab: @@ -153,7 +160,7 @@ if **Instance ID** will be single token or multiple tokens, assigned to the **Environment**. Also, **Application name** could describe the version of application instead of the running environment. -### Client libraries +## Client libraries GitLab currently implements a single backend that is compatible with [Unleash](https://github.com/Unleash/unleash#client-implementations) clients. @@ -178,7 +185,7 @@ Community contributed clients: - [Unofficial .Net Core Unleash client](https://github.com/onybo/unleash-client-core) - [Unleash client for Python 3](https://github.com/aes/unleash-client-python) -### Golang application example +## Golang application example Here's an example of how to integrate the feature flags in a Golang application: @@ -219,7 +226,7 @@ func main() { } ``` -### Ruby application example +## Ruby application example Here's an example of how to integrate the feature flags in a Ruby application. @@ -249,3 +256,11 @@ else puts "hello, world!" end ``` + +## Feature Flags API + +You can create, update, read, and delete Feature Flags via API +to control them in an automated flow: + +- [Feature Flags API](../../../api/feature_flags.md) +- [Feature Flag Specs API](../../../api/feature_flag_specs.md) diff --git a/doc/user/project/operations/img/error_details_v12_5.png b/doc/user/project/operations/img/error_details_v12_5.png Binary files differnew file mode 100644 index 00000000000..5e3e6300640 --- /dev/null +++ b/doc/user/project/operations/img/error_details_v12_5.png diff --git a/doc/user/project/operations/img/error_tracking_list.png b/doc/user/project/operations/img/error_tracking_list.png Binary files differindex 194c7b440a4..79b464e021e 100644 --- a/doc/user/project/operations/img/error_tracking_list.png +++ b/doc/user/project/operations/img/error_tracking_list.png 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 326a2d302d2..2f16606c5a8 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 @@ -169,6 +169,22 @@ from the GitLab project. in place: your domain will be periodically reverified, and may be disabled if the record is removed. +##### Troubleshooting Pages domain verification + +To manually verify that you have properly configured the domain verification +`TXT` DNS entry, you can run the following command in your terminal: + +``` +dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT +``` + +Expect the output: + +``` +;; ANSWER SECTION: +_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" +``` + ### Adding more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. 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 c9b504dc6ee..1d64e843e46 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 @@ -5,7 +5,8 @@ description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." # GitLab Pages integration with Let's Encrypt -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). +This feature is in **beta** and may still have bugs. See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) for more information. The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains @@ -16,19 +17,11 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. CAUTION: **Caution:** -This feature is in **beta** and might present bugs and UX issues -such as [#64870](https://gitlab.com/gitlab-org/gitlab-foss/issues/64870). -See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) -for more information. - -CAUTION: **Caution:** -This feature covers only certificates for **custom domains**, -not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. -Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). ## Requirements -Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: +Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have: - Created a [project](../getting_started_part_two.md) in GitLab containing your website's source code. @@ -36,7 +29,7 @@ Before you can enable automatic provisioning of a SSL certificate for your domai pointing it to your Pages website. - [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) and verified your ownership. -- Have your website up and running, accessible through your custom domain. +- Verified your website is up and running, accessible through your custom domain. NOTE: **Note:** GitLab's Let's Encrypt integration is enabled and available on GitLab.com. @@ -45,7 +38,7 @@ For **self-managed** GitLab instances, make sure your administrator has ## Enabling Let's Encrypt integration for your custom domain -Once you've met the requirements, to enable Let's Encrypt integration: +Once you've met the requirements, enable Let's Encrypt integration: 1. Navigate to your project's **Settings > Pages**. 1. Find your domain and click **Details**. diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md new file mode 100644 index 00000000000..ac1a29ca2a0 --- /dev/null +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -0,0 +1,61 @@ +--- +type: reference, howto +--- + +# New Pages website from a forked sample + +To get started with GitLab Pages from a sample website, the easiest +way to do it is by using one of the [bundled templates](pages_bundled_template.md). +If you don't find one that suits your needs, you can opt by +forking (copying) a [sample project from the most popular Static Site Generators](https://gitlab.com/pages). + +<table class="borderless-table center fixed-table middle width-80"> + <tr> + <td style="width: 30%"><img src="../img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="../img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="../img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Fork an example project</em></td> + <td></td> + <td><em>Deploy your website</em></td> + <td></td> + <td><em>Visit your website's URL</em></td> + </tr> +</table> + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** + +1. [Fork](../../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site to the server. +1. Once the pipeline has finished successfully, find the link to visit your + website from your project's **Settings > Pages**. It can take aproximatelly + 30 minutes to be deployed. + +You can also take some **optional** further steps: + +- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: + +  + +- _Make it a user or group website._ To turn a **project website** forked + from the Pages group into a **user/group** website, you'll need to: + - Rename it to `namespace.gitlab.io`: go to your project's + **Settings > General** and expand **Advanced**. Scroll down to + **Rename repository** and change the path to `namespace.gitlab.io`. + - Adjust your SSG's [base URL](../getting_started_part_one.md#urls-and-baseurls) from `"project-name"` to + `""`. This setting will be at a different place for each SSG, as each of them + have their own structure and file tree. Most likely, it will be in the SSG's + config file. diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md new file mode 100644 index 00000000000..62b5fa33117 --- /dev/null +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -0,0 +1,45 @@ +--- +type: reference, howto +--- + +# Start a new Pages website from scratch or deploy an existing website + +If you already have a website and want to deploy it with GitLab Pages, +or, if you want to start a new site from scratch, you'll need to: + +- Create a new project in GitLab to hold your site content. +- Set up GitLab CI/CD to deploy your website to Pages. + +To do so, follow the steps below. + +1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, + click **New project**, and name it according to the + [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names). +1. Clone it to your local computer, add your website + files to your project, add, commit and push to GitLab. + Alternativelly, you can run `git init` in your local directory, + add the remote URL: + `git remote add origin git@gitlab.com:namespace/project-name.git`, + then add, commit, and push to GitLab. +1. From the your **Project**'s page, click **Set up CI/CD**: + +  + +1. Choose one of the templates from the dropbox menu. + Pick up the template corresponding to the SSG you're using (or plain HTML). + +  + + Note that, if you don't find a corresponding template, you can look into + [GitLab Pages group of sample projects](https://gitlab.com/pages), + you may find one among them that suits your needs, from which you + can copy `.gitlab-ci.yml`'s content and adjust for your case. + If you don't find it there either, [learn how to write a `.gitlab-ci.yml` + file for GitLab Pages](../getting_started_part_four.md). + +Once you have both site files and `.gitlab-ci.yml` in your project's +root, GitLab CI/CD will build your site and deploy it with Pages. +Once the first build passes, you access your site by +navigating to your **Project**'s **Settings** > **Pages**, +where you'll find its default URL. It can take approximately 30 min to be +deployed. diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md new file mode 100644 index 00000000000..802abeb3cc2 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -0,0 +1,29 @@ +--- +type: reference, howto +--- + +# New Pages website from a bundled template + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) +in GitLab 11.8. + +The simplest way to create a GitLab Pages site is to use one of the most +popular templates, which come already bundled with GitLab and are ready to go. + +1. From the top navigation, click the **+** button and select **New project**. +1. Select **Create from Template**. +1. Choose one of the templates starting with **Pages**: + +  + +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site to the server. +1. After the pipeline has finished successfully, wait approximately 30 minutes + for your website to be visible. After waiting 30 minutes, find the link to + visit your website from your project's **Settings > Pages**. If the link + leads to a 404 page, wait a few minutes and try again. + +Your website is then visible on your domain and you can modify your files +as you wish. For every modification pushed to your repository, GitLab CI/CD +will run a new pipeline to immediately publish your changes to the server. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 0b1cae9ab4c..b876e547ba5 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -3,25 +3,12 @@ last_updated: 2018-06-04 type: concepts, reference --- -# Static sites and GitLab Pages domains +# GitLab Pages domain names, URLs, and baseurls On this document, learn how to name your project for GitLab Pages according to your intended website's URL. -## Static sites - -GitLab Pages only supports static websites, meaning, -your output files must be HTML, CSS, and JavaScript only. - -To create your static site, you can either hardcode in HTML, -CSS, and JS, or use a [Static Site Generator (SSG)](https://www.staticgen.com/) -to simplify your code and build the static site for you, -which is highly recommendable and much faster than hardcoding. - -See the [further reading](#further-reading) section below for -references on static site concepts. - -## GitLab Pages domain names +## GitLab Pages default domain names >**Note:** If you use your own GitLab instance to deploy your @@ -93,11 +80,35 @@ To understand Pages domains clearly, read the examples below. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ +## URLs and baseurls + +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 +documentation and set it up to reflect this pattern. + +For example, for a Jekyll site, the `baseurl` is defined in the Jekyll +configuration file, `_config.yml`. If your website URL is +`https://john.gitlab.io/blog/`, you need to add this line to `_config.yml`: + +```yaml +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: + +```yaml +baseurl: "" +``` -### Further reading +## Custom domains -- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) -- Understand [how modern Static Site Generators work](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site -- You can use [any SSG with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -- Fork an [example project](https://gitlab.com/pages) to build your website based upon +GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. +See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index ff752917087..70e84f5d486 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,172 +1,5 @@ --- -last_updated: 2019-06-04 -type: reference, howto +redirect_to: 'index.md' --- -# Projects for GitLab Pages and URL structure - -## What you need to get started - -To get started with GitLab Pages, you need: - -1. A project, thus a repository to hold your website's codebase. -1. A configuration file (`.gitlab-ci.yml`) to deploy your site. -1. A specific `job` called `pages` in the configuration file - that will make GitLab aware that you are deploying a GitLab Pages website. -1. A `public` directory with the static content of the website. - -Optional Features: - -1. A custom domain or subdomain. -1. A DNS pointing your (sub)domain to your Pages site. - 1. **Optional**: an SSL/TLS certificate so your custom - domain is accessible under HTTPS. - -The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)). - -## Project - -Your GitLab Pages project is a regular project created the -same way you do for the other ones. To get started with GitLab Pages, you have three ways: - -- [Use one of the popular project templates bundled with GitLab](#use-one-of-the-popular-pages-templates-bundled-with-gitlab). -- [Fork one of the templates from Page Examples](#fork-a-project-to-get-started-from). -- [Create a new project from scratch](#create-a-project-from-scratch). - -### Use one of the popular Pages templates bundled with GitLab - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) -in GitLab 11.8. - -The simplest way to create a GitLab Pages site is to -[use one of the most popular templates](index.md#getting-started), -which come already bundled with GitLab and are ready to go. - -### Fork a project to get started from - -If you don't find an existing project template that suits you, -we've created this [group](https://gitlab.com/pages) of default projects -containing the most popular SSGs templates to get you started. - -<table class="borderless-table center fixed-table middle width-80"> - <tr> - <td style="width: 30%"><img src="img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Fork an example project</em></td> - <td></td> - <td><em>Deploy your website</em></td> - <td></td> - <td><em>Visit your website's URL</em></td> - </tr> -</table> - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** - -1. [Fork](../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. Once the pipeline has finished successfully, find the link to visit your - website from your project's **Settings > Pages**. - -You can also take some **optional** further steps: - -- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: - -  - -- _Make it a user or group website._ To turn a **project website** forked - from the Pages group into a **user/group** website, you'll need to: - - Rename it to `namespace.gitlab.io`: go to your project's - **Settings > General** and expand **Advanced**. Scroll down to - **Rename repository** and change the path to `namespace.gitlab.io`. - - Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to - `""`. This setting will be at a different place for each SSG, as each of them - have their own structure and file tree. Most likely, it will be in the SSG's - config file. - -### Create a project from scratch - -1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, - click **New project**, and name it according to the - [Pages domain names](getting_started_part_one.md#gitlab-pages-domain-names). -1. Clone it to your local computer, add your website - files to your project, add, commit and push to GitLab. -1. From the your **Project**'s page, click **Set up CI/CD**: - -  - -1. Choose one of the templates from the dropbox menu. - Pick up the template corresponding to the SSG you're using (or plain HTML). - -  - -Once you have both site files and `.gitlab-ci.yml` in your project's -root, GitLab CI/CD will build your site and deploy it with Pages. -Once the first build passes, you see your site is live by -navigating to your **Project**'s **Settings** > **Pages**, -where you'll find its default URL. - -> **Notes:** -> -> - GitLab Pages [supports any SSG](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but, -> if you don't find yours among the templates, you'll need -> to configure your own `.gitlab-ci.yml`. To do that, please -> read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among -> the [example projects](https://gitlab.com/pages). If you set -> up a new one, please -> [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) -> to our examples. -> -> - The second step _"Clone it to your local computer"_, can be done -> differently, achieving the same results: instead of cloning the bare -> repository to you local computer and moving your site files into it, -> you can run `git init` in your local website directory, add the -> remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, -> then add, commit, and push to GitLab. - -## URLs and Baseurls - -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 -documentation and set it up to reflect this pattern. - -For example, for a Jekyll site, the `baseurl` is defined in the Jekyll -configuration file, `_config.yml`. If your website URL is -`https://john.gitlab.io/blog/`, you need to add this line to `_config.yml`: - -```yaml -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: - -```yaml -baseurl: "" -``` - -## Custom Domains - -GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. -See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. +This document was moved to [another location](index.md#getting-started). diff --git a/doc/user/project/pages/img/new_project_for_pages_v12_5.png b/doc/user/project/pages/img/new_project_for_pages_v12_5.png Binary files differnew file mode 100644 index 00000000000..8d2dc0bf9f5 --- /dev/null +++ b/doc/user/project/pages/img/new_project_for_pages_v12_5.png diff --git a/doc/user/project/pages/img/pages_workflow_v12_5.png b/doc/user/project/pages/img/pages_workflow_v12_5.png Binary files differnew file mode 100644 index 00000000000..ca5190fca79 --- /dev/null +++ b/doc/user/project/pages/img/pages_workflow_v12_5.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 7d533c6f9d1..abd67c90dd6 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -19,38 +19,7 @@ You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content. -<table class="borderless-table center fixed-table"> - <tr> - <td style="width: 22%"><img src="img/icons/cogs.png" alt="SSGs" class="image-noshadow half-width"></td> - <td style="width: 4%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 22%"><img src="img/icons/monitor.png" alt="Websites" class="image-noshadow half-width"></td> - <td style="width: 4%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 22%"><img src="img/icons/free.png" alt="Pages is free" class="image-noshadow half-width"></td> - <td style="width: 4%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 22%"><img src="img/icons/lock.png" alt="Secure your website" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Use any static website generator or plain HTML</em></td> - <td></td> - <td><em>Create websites for your projects, groups, or user account</em></td> - <td></td> - <td><em>Host on GitLab.com for free, or on your own GitLab instance</em></td> - <td></td> - <td><em>Connect your custom domain(s) and TLS certificates</em></td> - </tr> -</table> +<img src="img/pages_workflow_v12_5.png" alt="Pages websites workflow" class="image-noshadow"> Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate). @@ -73,6 +42,7 @@ publish any website written directly in plain HTML, CSS, and JavaScript.</p> To use GitLab Pages, first you need to create a project in GitLab to upload your website's files to. These projects can be either public, internal, or private, at your own choice. + GitLab will always deploy your website from a very specific folder called `public` in your repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md) becomes available automatically. @@ -80,67 +50,50 @@ becomes available automatically. To deploy your site, GitLab will use 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_part_four.md) at will. +`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain-names), +You can either use GitLab's [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 need admin access to your domain's registrar (or control panel) to set it up with Pages. -Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your -site under the HTTPS protocol. - ### Getting started To get started with GitLab Pages, you can either: -- [Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch). -- [Copy an existing example project](getting_started_part_two.md#fork-a-project-to-get-started-from). -- Use a bundled project template ready to go: - -1. From the top navigation, click the **+** button and select **New project**. -1. Select **Create from Template**. -1. Choose one of the templates starting with **Pages**: - -  +- [Use a bundled website template ready to go](getting_started/pages_bundled_template.md). +- [Copy an existing sample](getting_started/fork_sample_project.md). +- [Create a website from scratch or deploy an existing one](getting_started/new_or_existing_website.md). -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. After the pipeline has finished successfully, wait approximately 30 minutes - for your website to be visible. After waiting 30 minutes, find the link to - visit your website from your project's **Settings > Pages**. If the link - leads to a 404 page, wait a few minutes and try again. +<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> -Your website is then visible on your domain and you can modify your files -as you wish. For every modification pushed to your repository, GitLab CI/CD -will run a new pipeline to immediately publish your changes to the server. +Optional features: -_Advanced options:_ +- Use a [custom domain or subdomain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain). +- Add an [SSL/TLS certificate to secure your site under the HTTPS protocol](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages). -- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) -- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain +Note that, if you're using GitLab Pages default domain (`.gitlab.io`), +your website will be automatically secure and available under +HTTPS. If you're using your own custom domain, you can +optionally secure it with SSL/TLS certificates. ## Availability If you're using GitLab.com, your website will be publicly available to the internet. + +To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). + If you're using self-managed instances (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the [Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, who can opt for making them public or internal to your server. -Note that, if you're using GitLab Pages default domain (`.gitlab.io`), -your website will be automatically secure and available under -HTTPS. If you're using your own custom domain, you can -optionally secure it with SSL/TLS certificates. - ## Explore GitLab Pages To learn more about configuration options for GitLab Pages, read the following: | Document | Description | | --- | --- | -| [Static websites and Pages domains](getting_started_part_one.md) | Understand what is a static website, and how GitLab Pages default domains work. | -| [Projects and URL structure](getting_started_part_two.md) | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. | +| [GitLab Pages domain names, URLs, and baseurls](getting_started_part_one.md) | Understand how GitLab Pages default domains work. | | [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | | [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. | |---+---| diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 86257e2aa03..01e1909f6d6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -69,40 +69,7 @@ don't have to create and edit HTML files manually. For example, Jekyll has the ## GitLab Pages Access Control **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. - -You can enable Pages access control on your project, so that only -[members of your project](../../permissions.md#project-members-permissions) -(at least Guest) can access your website: - -1. Navigate to your project's **Settings > General > Permissions**. -1. Toggle the **Pages** button to enable the access control. - - NOTE: **Note:** - If you don't see the toggle button, that means that it's not enabled. - Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). - -1. The Pages access control dropdown allows you to set who can view pages hosted - 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. - - 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. - - 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. - -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 -can access the website. +To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). ## Unpublishing your Pages 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 1338c7e58f5..c9bd3e35a5f 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -21,8 +21,8 @@ open source Certificate Authority. To follow along with this tutorial, we assume you already have: -- Created a [project](getting_started_part_two.md) in GitLab which - contains your website's source code. +- [Created a project](index.md#getting-started) in GitLab + containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) pointing it to your Pages website. - [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md new file mode 100644 index 00000000000..cd715c6e3b9 --- /dev/null +++ b/doc/user/project/pages/pages_access_control.md @@ -0,0 +1,48 @@ +--- +type: reference, howto +--- + +# GitLab Pages Access Control + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. +> - Available on GitLab.com in GitLab 12.4. + +You can enable Pages access control on your project, so that only +[members of your project](../../permissions.md#project-members-permissions) +(at least Guest) can access your website: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Toggle the **Pages** button to enable the access control. + + NOTE: **Note:** + If you don't see the toggle button, that means that it's not enabled. + Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). + +1. The Pages access control dropdown allows you to set who can view pages hosted + 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. + - 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. + - 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. + +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 +can access the website. + +## Terminating a Pages session + +If you want to log out from your Pages website, +you can do so by revoking application access token for GitLab Pages: + +1. Navigate to your profile's **Settings > Applications**. +1. Find **Authorized applications** at the bottom of the page. +1. Find **GitLab Pages** and press the **Revoke** button. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index b7c9faeb1df..8ce575222b9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -55,7 +55,7 @@ the actions that different roles can perform with the protected branch. For example, you could set "Allowed to push" to "No one", and "Allowed to merge" to "Developers + Maintainers", to require _everyone_ to submit a merge request for changes going into the protected branch. This is compatible with workflows like -the [GitLab workflow](../../workflow/gitlab_flow.md). +the [GitLab workflow](../../topics/gitlab_flow.md). However, there are workflows where that is not needed, and only protecting from force pushes and branch removal is useful. For those workflows, you can allow @@ -118,10 +118,11 @@ all matching branches: When a protected branch or wildcard protected branches are set to [**No one** is **Allowed to push**](#using-the-allowed-to-merge-and-allowed-to-push-settings), -Developers (and users with higher [permission levels](../permissions.md)) are allowed -to create a new protected branch, but only via the UI or through the API (to avoid -creating protected branches accidentally from the command line or from a Git -client application). +Developers (and users with higher [permission levels](../permissions.md)) are +allowed to create a new protected branch as long as they are +[**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). +This can only be done via the UI or through the API (to avoid creating protected +branches accidentally from the command line or from a Git client application). To create a new branch through the user interface: diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 51c46dbd1d4..8952f845b96 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -75,3 +75,33 @@ merge request, and target a branch named `my-target-branch`: ```shell git push -o merge_request.create -o merge_request.target=my-target-branch ``` + +Additionally if you want the merge request to merge as soon as the pipeline succeeds you can do: + +```shell +git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds +``` + +## Useful Git aliases + +As shown above, Git push options can cause Git commands to grow very long. If +you use the same push options frequently, it's useful to create [Git +aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). Git aliases +are command line shortcuts for Git which can significantly simplify the use of +long Git commands. + +### Merge when pipeline succeeds alias + +To set up a Git alias for the [merge when pipeline succeeds Git push +option](#push-options-for-merge-requests): + +```shell +git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" +``` + +Then to quickly push a local branch that will target master and merge when the +pipeline succeeds: + +```shell +git mwps origin <local-branch-name> +``` diff --git a/doc/user/project/releases/img/edit_release_page_v12_5.png b/doc/user/project/releases/img/edit_release_page_v12_5.png Binary files differnew file mode 100644 index 00000000000..8b9c502a2ef --- /dev/null +++ b/doc/user/project/releases/img/edit_release_page_v12_5.png diff --git a/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png b/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png Binary files differnew file mode 100644 index 00000000000..2e3ec08ba87 --- /dev/null +++ b/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png diff --git a/doc/user/project/releases/img/milestone_with_releases_v12_5.png b/doc/user/project/releases/img/milestone_with_releases_v12_5.png Binary files differnew file mode 100644 index 00000000000..8719a58ce4e --- /dev/null +++ b/doc/user/project/releases/img/milestone_with_releases_v12_5.png diff --git a/doc/user/project/releases/img/new_tag_12_5.png b/doc/user/project/releases/img/new_tag_12_5.png Binary files differnew file mode 100644 index 00000000000..6137ad2ee56 --- /dev/null +++ b/doc/user/project/releases/img/new_tag_12_5.png diff --git a/doc/user/project/releases/img/release_edit_button_v12_5.png b/doc/user/project/releases/img/release_edit_button_v12_5.png Binary files differnew file mode 100644 index 00000000000..f60b0ecb1be --- /dev/null +++ b/doc/user/project/releases/img/release_edit_button_v12_5.png diff --git a/doc/user/project/releases/img/release_with_milestone_v12_5.png b/doc/user/project/releases/img/release_with_milestone_v12_5.png Binary files differnew file mode 100644 index 00000000000..2a7a2ee9754 --- /dev/null +++ b/doc/user/project/releases/img/release_with_milestone_v12_5.png diff --git a/doc/user/project/releases/img/tags_12_5.png b/doc/user/project/releases/img/tags_12_5.png Binary files differnew file mode 100644 index 00000000000..4c032f96125 --- /dev/null +++ b/doc/user/project/releases/img/tags_12_5.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index ceb077ab8af..8372aefc94c 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -58,6 +58,31 @@ links from your GitLab instance. NOTE: **NOTE** You can manipulate links of each release entry with [Release Links API](../../../api/releases/links.md) +#### Releases associated with milestones + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5. + +Releases can optionally be associated with one or more +[project milestones](../milestones/index.md#project-milestones-and-group-milestones) +by including a `milestones` array in your requests to the +[Releases API](../../../api/releases/index.md#create-a-release). + +Releases display this association with the **Milestone** indicator near +the top of the Release block on the **Project overview > Releases** page. + + + +Below is an example of milestones with no Releases, one Release, and two +Releases, respectively. + + + +This relationship is also visible in the **Releases** section of the sidebar +when viewing a specific milestone. Below is an example of a milestone +associated with a large number of Releases. + + + ## Releases list Navigate to **Project > Releases** in order to see the list of releases for a given @@ -65,6 +90,27 @@ project.  +## Editing a release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26016) in GitLab 12.5. + +To edit the details of a release, navigate to **Project overview > Releases** and click +the edit button (pencil icon) in the top-right corner of the release you want to modify. + + + +This will bring you to the **Edit Release** page, from which you can +change some of the release's details. + + + +Currently, it is only possible to edit the release title and notes. +To change other release information, such as its tag, associated +milestones, or release date, use the +[Releases API](../../../api/releases/index.md#update-a-release). Editing this +information through the **Edit Release** page is planned for a future version +of GitLab. + ## Notification for Releases > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26001) in GitLab 12.4. @@ -77,6 +123,91 @@ following modal window will be then displayed, from which you can select **New r  +## Add release notes to Git tags + +You can add release notes to any Git tag using the notes feature. Release notes +behave like any other markdown form in GitLab so you can write text and +drag and drop files to it. Release notes are stored in GitLab's database. + +There are several ways to add release notes: + +- In the interface, when you create a new Git tag. +- In the interface, by adding a note to an existing Git tag. +- Using the GitLab API. + +To create a new tag, navigate to your project's **Repository > Tags** and +click **New tag**. From there, you can fill the form with all the information +about the release: + + + +You can also edit an existing tag to add release notes: + + + +## Release Evidence + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26019) in GitLab 12.5. + +Each time a new release is created, specific related data is collected in +parallel. This dataset will be a snapshot this new release (including linked +milestones and issues) at moment of creation. Such collection of data will +provide a chain of custody and facilitate processes like external audits, for example. + +The gathered Evidence data is stored in the database upon creation of a new +release as a JSON object. In GitLab 12.5, a link to +the Evidence data is provided for [each Release](#releases-list). + +Here's what this object can look like: + +```json +{ + "release": { + "id": 5, + "tag": "v4.0", + "name": "New release", + "project_id": 45, + "project_name": "Project name", + "released_at": "2019-06-28 13:23:40 UTC", + "milestones": [ + { + "id": 11, + "title": "v4.0-rc1", + "state": "closed", + "due_date": "2019-05-12 12:00:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [ + { + "id": 82, + "title": "The top-right popup is broken", + "author_name": "John Doe", + "author_email": "john@doe.com", + "state": "closed", + "due_date": "2019-05-10 12:00:00 UTC" + }, + { + "id": 89, + "title": "The title of this page is misleading", + "author_name": "Jane Smith", + "author_email": "jane@smith.com", + "state": "closed", + "due_date": "nil" + } + ] + }, + { + "id": 12, + "title": "v4.0-rc2", + "state": "closed", + "due_date": "2019-05-30 18:30:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [] + } + ] + } +} +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md new file mode 100644 index 00000000000..576001d4305 --- /dev/null +++ b/doc/user/project/repository/file_finder.md @@ -0,0 +1,45 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' +--- + +# File finder + +> [Introduced][gh-9889] in GitLab 8.4. + +The file finder feature allows you to search for a file in a repository using the +GitLab UI. + +You can find the **Find File** button when in the **Files** section of a +project. + + + +For those who prefer to keep their fingers on the keyboard, there is a +[shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ +in a project. + +Press `t` to launch the File search function when in **Issues**, +**Merge requests**, **Milestones**, even the project's settings. + +Start typing what you are searching for and watch the magic happen. With the +up/down arrows, you go up and down the results, with `Esc` you close the search +and go back to **Files**. + +## How it works + +The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. + +It implements a fuzzy search with highlight, and tries to provide intuitive +results by recognizing patterns that people use while searching. + +For example, consider the [GitLab CE repository][ce] and that we want to open +the `app/controllers/admin/deploy_keys_controller.rb` file. + +Using fuzzy search, we start by typing letters that get us closer to the file. + +**Protip:** To narrow down your search, include `/` in your search terms. + + + +[gh-9889]: https://github.com/gitlabhq/gitlabhq/pull/9889 "File finder pull request" +[ce]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master "GitLab CE repository" diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md new file mode 100644 index 00000000000..8756760fe4b --- /dev/null +++ b/doc/user/project/repository/forking_workflow.md @@ -0,0 +1,55 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' +--- + +# Project forking workflow + +Forking a project to your own namespace is useful if you have no write +access to the project you want to contribute to. If you do have write +access or can request it, we recommend working together in the same +repository since it is simpler. See our [GitLab Flow](../../../topics/gitlab_flow.md) +document more information about using branches to work together. + +## Creating a fork + +Forking a project is in most cases a two-step process. + +1. Click on the fork button located located in between the star and clone buttons on the project's home page. + +  + +1. Once you do that, you'll be presented with a screen where you can choose + the namespace to fork to. Only namespaces (groups and your own + namespace) where you have write access to, will be shown. Click on the + namespace to create your fork there. + +  + + **Note:** + If the namespace you chose to fork the project to has another project with + the same path name, you will be presented with a warning that the forking + could not be completed. Try to resolve the error before repeating the forking + process. + +  + +After the forking is done, you can start working on the newly created +repository. There, you will have full [Owner](../../permissions.md) +access, so you can set it up as you please. + +## Merging upstream + +Once you are ready to send your code back to the main project, you need +to create a merge request. Choose your forked project's main branch as +the source and the original project's main branch as the destination and +create the [merge request](../merge_requests/index.md). + + + +You can then assign the merge request to someone to have them review +your changes. Upon pressing the 'Submit Merge Request' button, your +changes will be added to the repository and branch you're merging into. + + + +[gitlab flow]: https://about.gitlab.com/blog/2014/09/29/gitlab-flow/ "GitLab Flow blog post" diff --git a/doc/user/project/repository/img/file_finder_find_button.png b/doc/user/project/repository/img/file_finder_find_button.png Binary files differnew file mode 100644 index 00000000000..0c2d7d7bc73 --- /dev/null +++ b/doc/user/project/repository/img/file_finder_find_button.png diff --git a/doc/user/project/repository/img/file_finder_find_file.png b/doc/user/project/repository/img/file_finder_find_file.png Binary files differnew file mode 100644 index 00000000000..c2212c7cd9e --- /dev/null +++ b/doc/user/project/repository/img/file_finder_find_file.png diff --git a/doc/user/project/repository/img/forking_workflow_branch_select.png b/doc/user/project/repository/img/forking_workflow_branch_select.png Binary files differnew file mode 100644 index 00000000000..0ea5410f832 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_branch_select.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace.png b/doc/user/project/repository/img/forking_workflow_choose_namespace.png Binary files differnew file mode 100644 index 00000000000..eb023ca85f2 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace.png diff --git a/doc/user/project/repository/img/forking_workflow_fork_button.png b/doc/user/project/repository/img/forking_workflow_fork_button.png Binary files differnew file mode 100644 index 00000000000..7fb07529b6d --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_fork_button.png diff --git a/doc/user/project/repository/img/forking_workflow_merge_request.png b/doc/user/project/repository/img/forking_workflow_merge_request.png Binary files differnew file mode 100644 index 00000000000..43851203f3f --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_merge_request.png diff --git a/doc/user/project/repository/img/forking_workflow_path_taken_error.png b/doc/user/project/repository/img/forking_workflow_path_taken_error.png Binary files differnew file mode 100644 index 00000000000..ef62d0ab6a9 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_path_taken_error.png diff --git a/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png b/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png Binary files differnew file mode 100644 index 00000000000..e20dae09a4d --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png diff --git a/doc/user/project/repository/img/repository_mirroring_force_update.png b/doc/user/project/repository/img/repository_mirroring_force_update.png Binary files differnew file mode 100644 index 00000000000..1e6dcb9ea08 --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_force_update.png diff --git a/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png b/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png Binary files differnew file mode 100644 index 00000000000..a3e0b74ddf8 --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png diff --git a/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png b/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png Binary files differnew file mode 100644 index 00000000000..8e15b5a0784 --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png diff --git a/doc/user/project/repository/img/repository_mirroring_push_settings.png b/doc/user/project/repository/img/repository_mirroring_push_settings.png Binary files differnew file mode 100644 index 00000000000..3c0eacaa2df --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_push_settings.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index c14783b72bd..5a6e011220c 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -11,7 +11,8 @@ A repository is part of a [project](../index.md), which has a lot of other featu ## Create a repository To create a new repository, all you need to do is -[create a new project](../../../gitlab-basics/create-project.md). +[create a new project](../../../gitlab-basics/create-project.md) or +[fork an existing project](forking_workflow.md). Once you create a new project, you can add new files via UI (read the section below) or via command line. @@ -55,7 +56,7 @@ To get started with the command line, please read through the ### Find files -Use GitLab's [file finder](../../../workflow/file_finder.md) to search for files in a repository. +Use GitLab's [file finder](file_finder.md) to search for files in a repository. ### Supported markup languages and extensions diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md new file mode 100644 index 00000000000..a682983ab83 --- /dev/null +++ b/doc/user/project/repository/repository_mirroring.md @@ -0,0 +1,430 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +--- + +# 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. + +A repository mirror at GitLab will be updated automatically. You can also manually trigger an update +at most once every 5 minutes. + +## 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)** + +When the mirror repository is updated, all new branches, tags, and commits will be visible in the +project's activity feed. + +Users with at least [developer access](../../permissions.md) to the project can also force an +immediate update, unless: + +- The mirror is already being updated. +- 5 minutes haven't elapsed since its last update. + +## Use cases + +The following are some possible use cases for repository mirroring: + +- You migrated to GitLab but still need to keep your project in another source. In that case, you + can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + and branches will be available in your GitLab instance. **(STARTER)** +- You have old projects in another source that you don't use actively anymore, but don't want to + remove for archiving purposes. In that case, you can create a push mirror so that your active + GitLab repository can push its changes to the old location. + +## Pushing to a remote repository **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/249) in GitLab Enterprise Edition 8.7. +> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/18715) in 10.8. + +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. Check the **Only mirror protected branches** box, if necessary. +1. Click the **Mirror repository** button to save the configuration. + + + +When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the +mirror diverging. All changes will end up in the mirrored repository whenever: + +- Commits are pushed to GitLab. +- A [forced update](#forcing-an-update-core) is initiated. + +Changes pushed to files in the repository are automatically pushed to the remote mirror at least: + +- Within five minutes of being received. +- Within one minute if **Only mirror protected branches** is enabled. + +In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories** +section. + +### 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. + +## Setting up a push mirror from GitLab to GitHub **(CORE)** + +To set up a mirror from GitLab to GitHub, you need to follow these steps: + +1. Create a [GitHub personal access token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) with the `public_repo` box checked. +1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. +1. Fill in **Password** field with your GitHub personal access token. +1. Click the **Mirror repository** button. + +The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. + +The repository will push soon. To force a push, click the appropriate button. + +## 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 `API` scope. +1. On the source GitLab instance: + 1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + 1. Fill in **Password** field with the GitLab personal access token created on the destination GitLab instance. + 1. Click the **Mirror repository** button. + +## Pulling from a remote repository **(STARTER)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/51) in GitLab Enterprise Edition 8.2. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. + +NOTE: **Note:** This feature [is available for free](https://gitlab.com/gitlab-org/gitlab/issues/10361) to +GitLab.com users until March 22nd, 2020. + +You can set up a repository to automatically have its branches, tags, and commits updated from an +upstream repository. + +This is useful when a repository you're interested in is located on a different server, and you want +to be able to browse its content and its activity using the familiar GitLab interface. + +To configure mirror pulling for an existing project: + +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** + section. +1. Enter a repository URL. +1. Select **Pull** from the **Mirror direction** dropdown. +1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. If necessary, check the following boxes: + - **Overwrite diverged branches**. + - **Trigger pipelines for mirror updates**. + - **Only mirror protected branches**. +1. Click the **Mirror repository** button to save the configuration. + + + +--- + + + +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: + +- Automatically within a certain period of time. +- When a [forced update](#forcing-an-update-core) is initiated. + +CAUTION: **Caution:** +If you do manually update a branch in the GitLab repository, the branch will become diverged from +upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. + +### How it works + +Once the pull mirroring feature has been enabled for a repository, the repository is added to a queue. + +Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: + +- The capacity available. This is determined by Sidekiq settings. For GitLab.com, see [GitLab.com Sidekiq settings](../../gitlab_com/index.md#sidekiq). +- The number of repository mirrors already in the queue that are due to be updated. Being due depends on when the repository mirror was last updated and how many times it's been retried. + +Repository mirrors are updated as Sidekiq becomes available to process them. If the process of updating the repository mirror: + +- Succeeds, an update will be enqueued again with at least a 30 minute wait. +- 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 + +> - [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 is mutual: + +- You have to prove to the server that you're allowed to access the repository. +- The server also has to prove to *you* that it's who it claims to be. + +You provide your credentials as a password or public key. The server that the +other repository resides on provides its credentials as a "host key", the +fingerprint of which needs to be verified manually. + +If you're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using: + +- Password-based authentication, just as over HTTPS. +- Public key authentication. This is often more secure than password authentication, + especially when the other repository supports [Deploy Keys](../../../ssh/README.md#deploy-keys). + +To get started: + +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. Enter an `ssh://` URL for mirroring. + +NOTE: **Note:** +SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. + +Entering the URL adds two buttons to the page: + +- **Detect host keys**. +- **Input host keys manually**. + +If you click the: + +- **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints. +- **Input host keys manually** button, a field is displayed where you can paste in host keys. + +Assuming you used the former, you now need to verify that the fingerprints are +those you expect. GitLab.com and other code hosting sites publish their +fingerprints in the open for you to check: + +- [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) +- [Bitbucket](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html) +- [GitHub](https://help.github.com/en/articles/githubs-ssh-key-fingerprints) +- [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) +- [Launchpad](https://help.launchpad.net/SSHFingerprints) +- [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) +- [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) + +Other providers will vary. If you're running self-managed GitLab, or otherwise +have access to the server for the other repository, you can securely gather the +key fingerprints: + +```sh +$ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - +256 MD5:f4:28:9f:23:99:15:21:1b:bf:ed:1f:8e:a0:76:b2:9d root@example.com (ECDSA) +256 MD5:e6:eb:45:8a:3c:59:35:5f:e9:5b:80:12:be:7e:22:73 root@example.com (ED25519) +2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) +``` + +NOTE: **Note:** +You may need to exclude `-E md5` for some older versions of SSH. + +When mirroring the repository, GitLab will now check that at least one of the +stored host keys matches before connecting. This can prevent malicious code from +being injected into your mirror, or your password being stolen. + +### SSH public key authentication + +To use SSH public key authentication, you'll also need to choose that option +from the **Authentication method** dropdown. When the mirror is created, +GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SSH public key** button. + + + +You then need to add the public SSH key to the other repository's configuration: + +- If the other repository is hosted on GitLab, you should add the public SSH key + as a [Deploy Key](../../../ssh/README.md#deploy-keys). +- If the other repository is hosted elsewhere, you may need to add the key to + your user's `authorized_keys` file. Paste the entire public SSH key into the + file on its own line and save it. + +If you need to change the key at any time, you can remove and re-add the mirror +to generate a new key. You'll have to update the other repository with the new +key to keep the mirror running. + +### 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. + +CAUTION: **Caution:** +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-core). + +### 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-starter), +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-starter). + +## Forcing an update **(CORE)** + +While mirrors are scheduled to update automatically, you can always force an update by using the +update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. + + + +## Bidirectional mirroring **(STARTER)** + +CAUTION: **Caution:** +Bidirectional mirroring may cause conflicts. + +If you configure a GitLab repository to both pull from, and push to, the same remote source, there +is no guarantee that either repository will update correctly. If you set up a repository for +bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve +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-starter). +- [Pushing only protected branches](#push-only-protected-branches-core). + +You should [protect the branches](../protected_branches.md) you wish to mirror on both +remotes to prevent conflicts caused by rewriting history. + +Bidirectional mirroring also creates a race condition where commits made close together to the same +branch causes conflicts. The race condition can be mitigated by reducing the mirroring delay by using +a [Push event webhook](../integrations/webhooks.md#push-events) to trigger an immediate +pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring +protected branches. + +### Preventing conflicts using a `pre-receive` hook + +CAUTION: **Warning:** +The solution proposed will negatively impact the performance of +Git push operations because they will be proxied to the upstream Git +repository. + +A server-side `pre-receive` hook can be used to prevent the race condition +described above by only accepting the push after first pushing the commit to +the upstream Git repository. In this configuration one Git repository acts as +the authoritative upstream, and the other as downstream. The `pre-receive` hook +will be installed on the downstream repository. + +Read about [configuring custom Git hooks](../../../administration/custom_hooks.md) on the GitLab server. + +A sample `pre-receive` hook is provided below. + +```bash +#!/usr/bin/env bash + +# --- Assume only one push mirror target +# Push mirroring remotes are named `remote_mirror_<id>`, this finds the first remote and uses that. +TARGET_REPO=$(git remote | grep -m 1 remote_mirror) + +proxy_push() +{ + # --- Arguments + OLDREV=$(git rev-parse $1) + NEWREV=$(git rev-parse $2) + REFNAME="$3" + + # --- Pattern of branches to proxy pushes + whitelisted=$(expr "$branch" : "\(master\)") + + case "$refname" in + refs/heads/*) + branch=$(expr "$refname" : "refs/heads/\(.*\)") + + if [ "$whitelisted" = "$branch" ]; then + error="$(git push --quiet $TARGET_REPO $NEWREV:$REFNAME 2>&1)" + fail=$? + + if [ "$fail" != "0" ]; then + echo >&2 "" + echo >&2 " Error: updates were rejected by upstream server" + echo >&2 " This is usually caused by another repository pushing changes" + echo >&2 " to the same ref. You may want to first integrate remote changes" + echo >&2 "" + return + fi + fi + ;; + esac +} + +# Allow dual mode: run from the command line just like the update hook, or +# if no arguments are given then run as a hook script +if [ -n "$1" -a -n "$2" -a -n "$3" ]; then + # Output to the terminal in command line mode - if someone wanted to + # resend an email; they could redirect the output to sendmail + # themselves + PAGER= proxy_push $2 $3 $1 +else + # Push is proxied upstream one ref at a time. Because of this it is possible + # for some refs to succeed, and others to fail. This will result in a failed + # push. + while read oldrev newrev refname + do + proxy_push $oldrev $newrev $refname + done +fi +``` + +### Mirroring with Perforce Helix via Git Fusion **(STARTER)** + +CAUTION: **Warning:** +Bidirectional mirroring should not be used as a permanent configuration. Refer to +[Migrating from Perforce Helix](../import/perforce.md) for alternative migration approaches. + +[Git Fusion](https://www.perforce.com/manuals/git-fusion/#Git-Fusion/section_avy_hyc_gl.html) provides a Git interface +to [Perforce Helix](https://www.perforce.com/products) which can be used by GitLab to bidirectionally +mirror projects with GitLab. This may be useful in some situations when migrating from Perforce Helix +to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. + +If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix +will reject any pushes that rewrite history. Only the fewest number of branches should be mirrored +due to the performance limitations of Git Fusion. + +When configuring mirroring with Perforce Helix via Git Fusion, the following Git Fusion +settings are recommended: + +- `change-pusher` should be disabled. Otherwise, every commit will be rewritten as being committed + by the mirroring account, rather than being mapped to existing Perforce Helix users or the `unknown_git` user. +- `unknown_git` user will be used as the commit author if the GitLab user does not exist in + Perforce Helix. + +Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manuals/git-fusion/Content/Git-Fusion/section_vss_bdw_w3.html#section_zdp_zz1_3l). + +## Troubleshooting + +Should an error occur during a push, GitLab will display an "Error" highlight for that repository. Details on the error can then be seen by hovering over the highlight text. + +### 13:Received RST_STREAM with error code 2 with GitHub + +If you receive an "13:Received RST_STREAM with error code 2" while mirroring to a GitHub repository, your GitHub settings might be set to block pushes that expose your email address used in commits. Either set your email address on GitHub to be public, or disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 131999dbf60..2dc507901d0 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -49,10 +49,11 @@ Add an [issue description template](../description_templates.md#description-temp Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.html)). -- Merge request [description templates](../description_templates.md#description-templates). +- Add merge request [description templates](../description_templates.md#description-templates). - Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)** -- Enable [merge only of pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). +- Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). +- Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). +- Enable [`delete source branch after merge` option by default](../merge_requests/creating_merge_requests.md#deleting-the-source-branch)  diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md new file mode 100644 index 00000000000..9cdee0f2b5a --- /dev/null +++ b/doc/user/project/time_tracking.md @@ -0,0 +1,92 @@ +--- +type: reference +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' +--- + +# Time Tracking + +> Introduced in GitLab 8.14. + +Time Tracking allows you to track estimates and time spent on issues and merge +requests within GitLab. + +## Overview + +Time Tracking allows you to: + +- Record the time spent working on an issue or a merge request. +- Add an estimate of the amount of time needed to complete an issue or a merge + request. + +You don't have to indicate an estimate to enter the time spent, and vice versa. + +Data about time tracking is shown on the issue/merge request sidebar, as shown +below. + + + +## How to enter data + +Time Tracking uses two [quick actions](quick_actions.md) +that GitLab introduced with this new feature: `/spend` and `/estimate`. + +Quick actions can be used in the body of an issue or a merge request, but also +in a comment in both an issue or a merge request. + +Below is an example of how you can use those new quick actions inside a comment. + + + +Adding time entries (time spent or estimates) is limited to project members. + +### Estimates + +To enter an estimate, write `/estimate`, followed by the time. For example, if +you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write +`/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of +this help page. + +Every time you enter a new time estimate, any previous time estimates will be +overridden by this new value. There should only be one valid estimate in an +issue or a merge request. + +To remove an estimation entirely, use `/remove_estimate`. + +### Time spent + +To enter a time spent, use `/spend 3d 5h 10m`. + +Every new time spent entry will be added to the current total time spent for the +issue or the merge request. + +You can remove time by entering a negative amount: `/spend -3d` will remove 3 +days from the total time spent. You can't go below 0 minutes of time spent, +so GitLab will automatically reset the time spent if you remove a larger amount +of time compared to the time that was entered already. + +To remove all the time spent at once, use `/remove_time_spent`. + +## Configuration + +The following time units are available: + +- Months (mo) +- Weeks (w) +- Days (d) +- Hours (h) +- Minutes (m) + +Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. + +### Limit displayed units to hours **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/29469/) in GitLab 12.1. + +In GitLab self-managed instances, the display of time units can be limited to +hours through the option in **Admin Area > Settings > Preferences** under **Localization**. + +With this option enabled, `75h` is displayed instead of `1w 4d 3h`. + +## Other interesting links + +- [Time Tracking landing page in the GitLab handbook](https://about.gitlab.com/solutions/time-tracking/) |
