diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 09:55:51 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 09:55:51 +0000 |
| commit | e8d2c2579383897a1dd7f9debd359abe8ae8373d (patch) | |
| tree | c42be41678c2586d49a75cabce89322082698334 /doc/user/project | |
| parent | fc845b37ec3a90aaa719975f607740c22ba6a113 (diff) | |
| download | gitlab-ce-e8d2c2579383897a1dd7f9debd359abe8ae8373d.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42
Diffstat (limited to 'doc/user/project')
113 files changed, 2250 insertions, 1858 deletions
diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index c3900d33cb8..cac283f6f18 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -92,7 +92,7 @@ Here's an example setup flow from scratch: 1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project. 1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project. 1. Install [NGINX Ingress](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx) in your cluster. -1. Set up [the base domain](../../user/project/clusters/index.md#base-domain) based on the Ingress +1. Set up [the base domain](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) based on the Ingress Endpoint assigned above. 1. Check if [`v2.0.0+` of `auto-deploy-image` is used in your Auto DevOps pipelines](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). If it isn't, follow the documentation to specify the image version. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 58bdb3d698f..7d006247177 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,85 +4,57 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding EKS clusters **(FREE)** +# EKS clusters (DEPRECATED) **(FREE)** -GitLab supports adding new and existing EKS clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -## EKS requirements +WARNING: +Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. -Before creating your first cluster on Amazon EKS with the GitLab integration, make sure the following -requirements are met: +Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic +Kubernetes Service (EKS). -- 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. -- If you want to use an [existing EKS cluster](#existing-eks-cluster): - - An Amazon EKS cluster with worker nodes properly configured. - - `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) - for access to the EKS cluster. +## Add an existing EKS cluster -### Additional requirements for self-managed instances **(FREE SELF)** +If you already have an EKS cluster and want to integrate it with GitLab, +see how to [add an existing cluster](add_existing_cluster.md). -If you are using a self-managed GitLab instance, GitLab must first be configured with a set of -Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user -creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that -your users need to create EKS clusters. +## Create a new certificate-based EKS cluster -For example, the following policy document allows assuming a role whose name starts with -`gitlab-eks-` in account `123456789012`: +Prerequisites: -```json -{ - "Version": "2012-10-17", - "Statement": { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*" - } -} -``` +- An [Amazon Web Services](https://aws.amazon.com/) account. +- Permissions to manage IAM resources. -### Configure Amazon authentication +For instance-level clusters, see [additional requirements for self-managed instances](#additional-requirements-for-self-managed-instances). **(FREE SELF)** -To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and following the steps below. +To create new Kubernetes clusters for your project, group, or instance through the certificate-based method: -1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section. -1. Check **Enable Amazon EKS integration**. -1. Enter your **Account ID**. -1. Depending on your configuration, enter your access key and ID: +1. [Define the access control (RBAC or ABAC) for your cluster](cluster_access.md). +1. [Create a cluster in GitLab](#create-a-new-eks-cluster-in-gitlab). +1. [Prepare the cluster in Amazon](#prepare-the-cluster-in-amazon). +1. [Configure your cluster's data in GitLab](#configure-your-clusters-data-in-gitlab). - - _GitLab 13.7 and later, and using an instance profile_: You may leave - **Access key ID** and **Secret access key** blank. - Read [Instance profiles](#instance-profiles) for more information. - - _All GitLab versions_: Enter your access key credentials into - **Access key ID** and **Secret access key**. +Further steps: -1. Click **Save changes**. +1. [Create a default Storage Class](#create-a-default-storage-class). +1. [Deploy the app to EKS](#deploy-the-app-to-eks). -#### Instance profiles +### Create a new EKS cluster in GitLab -> Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/291015). +To create a new EKS cluster: -You may leave `Access key ID` and `Secret access key` fields blank if -you are using an instance profile -[to pass an IAM role to an EC2 instance](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html). -Instance profiles dynamically retrieve temporary credentials from AWS when needed. - -## New EKS cluster - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. - -To create and add a new Kubernetes cluster to your project, group, or instance: - -1. Navigate to your: +1. Go to your: - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - - **Admin Area > Kubernetes**, for an instance-level cluster. -1. Click **Integrate with a cluster certificate**. + - **Menu >** **{admin}** **Admin > Kubernetes**, for an instance-level cluster. +1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: 1. From the left panel, select **Policies**. - 1. Click **Create Policy**, which opens a new window. + 1. Select **Create Policy**, which opens a new window. 1. Select the **JSON** tab, and paste the following snippet in place of the existing content. These permissions give GitLab the ability to create resources, but not delete them: @@ -133,132 +105,163 @@ To create and add a new Kubernetes cluster to your project, group, or instance: } ``` - 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) + If you get an error during this process, GitLab does not roll back the changes. 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. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an **EKS IAM role** following the [Amazon EKS cluster IAM role instructions](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html). This role should exist so that Kubernetes clusters managed by Amazon EKS can make calls to other AWS services on your behalf to manage the resources that you use with the service. - In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` - policy for this role in order for GitLab to manage the EKS cluster correctly. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create another IAM role which will be used by GitLab to authenticate with AWS. Follow these steps to create it: - 1. On the AWS IAM console, select **Roles** from the left panel. - 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**, 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 displays 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. +### Prepare the cluster in Amazon + +1. [Create an **EKS IAM role** for your cluster](#create-an-eks-iam-role-for-your-cluster) (**role A**). +1. [Create **another EKS IAM role** for GitLab authentication with Amazon](#create-another-eks-iam-role-for-gitlab-authentication-with-amazon) (**role B**). + +#### Create an EKS IAM role for your cluster + +In the [IAM Management Console](https://console.aws.amazon.com/iam/home), +create an **EKS IAM role** (**role A**) following the [Amazon EKS cluster IAM role instructions](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html). +This role is necessary so that Kubernetes clusters managed by Amazon EKS can make calls to other AWS +services on your behalf to manage the resources that you use with the service. + +For GitLab to manage the EKS cluster correctly, you must include `AmazonEKSClusterPolicy` in +addition to the policies the guide suggests. + +#### Create another EKS IAM role for GitLab authentication with Amazon + +In the [IAM Management Console](https://console.aws.amazon.com/iam/home), +create another IAM role (**role B**) for GitLab authentication with AWS: + +1. On the AWS IAM console, select **Roles** from the left panel. +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**, 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 displays at the top. Click on its name and copy the + `Role ARN` from the newly created role. + +### Configure your cluster's data in GitLab + +1. Back in GitLab, enter the copied role ARN into the **Role ARN** field. 1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab confirms you have access to this region when authenticating your role. -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) to this cluster. - - **Kubernetes version** - The [Kubernetes version](index.md#supported-cluster-versions) to use. - - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS - and the Kubernetes control plane to manage AWS resources on your behalf. - - NOTE: - This IAM role is _not_ the IAM role you created in the previous step. It should be - the one you created much earlier by following the - [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) - guide. - - **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 run. You must select at least two. - - **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. +1. Select **Authenticate with AWS**. +1. Adjust your [cluster's settings](#cluster-settings). +1. Select the **Create Kubernetes cluster** button. After about 10 minutes, your cluster is ready to go. NOTE: -If you have [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) `kubectl` and you would like to manage your cluster with it, you must add your AWS external ID in the AWS configuration. For more information on how to configure AWS CLI, see [using an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount). - -### Cluster creation flow - -The following sequence illustrates how GitLab works with AWS to create an EKS cluster: - -```mermaid -sequenceDiagram - autonumber - participant G as GitLab - participant A as AWS - participant E as EKS cluster - alt static credentials - G->>G: Load AWS Access and secret key - end - alt IAM instance profile - G->>A: Fetch temporary credentials - A->>G: Temporary access credentials - end - G->>A: AssumeRole: EKS Provision Role - A->>A: Check account, external IDs - A->>A: Check permissions - A->>G: New access credentials - note over G: user selects EKS cluster options - note over G,A: Use Service Role credentials - G->>A: CreateStack (CloudFormation) - A->>G: Received - G->>G: Wait 5 minutes - loop Poll for cluster creation - G->>A: DescribeStacks - A->>G: CREATE_IN_PROGRESS - end - note over G,E: EKS Cluster Created - G->>A: DescribeStacks - A->>G: CREATE_COMPLETE - G->>E: kubectl create role (service account) - E->>G: OK +If you have [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) `kubectl` and you would like to manage your cluster with it, you must add your AWS external ID in the AWS configuration. For more information on how to configure AWS CLI, see [using an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount). + +#### Cluster settings + +When you create a new cluster, you have the following settings: + +| Setting | Description | +| ----------------------- |------------ | +| Kubernetes cluster name | Your cluster's name. | +| Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | +| Service role | The **EKS IAM role** (**role A**). | +| Kubernetes version | The [Kubernetes version](index.md#supported-cluster-versions) for your cluster. | +| Key pair name | 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. | +| VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | +| Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | +| Security group | 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 | Check if you want GitLab to manage namespaces and service accounts for this cluster. | + +## Create a default Storage Class + +Amazon EKS doesn't have a default Storage Class out of the box, which means +requests for persistent volumes are not automatically fulfilled. As part +of Auto DevOps, the deployed PostgreSQL instance requests persistent storage, +and without a default storage class it cannot 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 PostgreSQL by setting the project variable +[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#cicd-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 isn't externally available outside of the cluster. + + + +GitLab creates a new pipeline, which begins to build, test, and deploy the app. + +After the pipeline has finished, your app runs in EKS, and is available +to users. Click on **CI/CD > Environments**. + + + +GitLab displays 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. + +## Additional requirements for self-managed instances **(FREE SELF)** + +If you are using a self-managed GitLab instance, you need to configure +Amazon credentials. GitLab uses these credentials to assume an Amazon IAM role to create your cluster. + +Create an IAM user and ensure it has permissions to assume the role(s) that +your users need 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-*" + } +} ``` -First, GitLab must obtain an initial set of credentials to communicate with the AWS API. -These credentials can be retrieved in one of two ways: +### Configure Amazon authentication + +To configure Amazon authentication in GitLab, generate an access key for the +IAM user in the Amazon AWS console, and follow these steps: -- Statically through the [Configure Amazon authentication](#configure-amazon-authentication). -- Dynamically via an IAM instance profile ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7). +1. In GitLab, on the top bar, select **Menu >** **{admin}** **Admin > Settings > General** and expand the **Amazon EKS** section. +1. Check **Enable Amazon EKS integration**. +1. Enter your **Account ID**. +1. Enter your [access key and ID](#eks-access-key-and-id). +1. Click **Save changes**. -After GitLab retrieves the AWS credentials, it makes an -[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) -API call to obtain credentials for the Provision Role. AWS confirms -the request has the correct account ID, external ID, and permissions. +#### EKS access key and ID -If the request is valid, AWS returns a new set of temporary credentials GitLab -uses to load the **Create cluster** options page. +> Instance profiles were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7. -On the **Create cluster** page, the user must select a **Service Role**, which is -the IAM role that is actually used to create the cluster, and other options -such as the Kubernetes cluster name, Kubernetes version, and region. -After the user clicks the **Create Kubernetes cluster** button, GitLab -submits a CloudFormation API request to create an EKS cluster with the given parameters -from the user. GitLab waits 5 minutes before checking whether the cluster was created, -and polls once a minute for up to 30 minutes. +If you're using GitLab 13.7 or later, you can use instance profiles to +dynamically retrieve temporary credentials from AWS when needed. +In this case, leave the `Access key ID` and `Secret access key` fields blank +and [pass an IAM role to an EC2 instance](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html). -After GitLab receives a `CREATE_COMPLETE` message from AWS, GitLab talks -to the EKS cluster to create a Kubernetes service account with `cluster-admin` -privileges, and updates its internal database to reflect the newly-created -Kubernetes cluster. From this point forward, GitLab uses this service account to -interact with the cluster. +Otherwise, enter your access key credentials into **Access key ID** and **Secret access key**. -### Troubleshooting creating a new cluster +## Troubleshooting The following errors are commonly encountered when creating a new cluster. -#### Validation failed: Role ARN must be a valid Amazon Resource Name +### Validation failed: Role ARN must be a valid Amazon Resource Name Check that the `Provision Role ARN` is correct. An example of a valid ARN: @@ -266,7 +269,7 @@ Check that the `Provision Role ARN` is correct. An example of a valid ARN: arn:aws:iam::123456789012:role/gitlab-eks-provision' ``` -#### Access denied: User `arn:aws:iam::x` is not authorized to perform: `sts:AssumeRole` on resource: `arn:aws:iam::y` +### Access denied: User `arn:aws:iam::x` is not authorized to perform: `sts:AssumeRole` on resource: `arn:aws:iam::y` This error occurs when the credentials defined in the [Configure Amazon authentication](#configure-amazon-authentication) cannot assume the role defined by the @@ -280,7 +283,7 @@ Provision Role ARN. Check that:  -#### Could not load Security Groups for this VPC +### Could not load Security Groups for this VPC When populating options in the configuration form, GitLab returns this error because GitLab has successfully assumed your provided role, but the role has @@ -307,46 +310,3 @@ This role should be the role you created by following the [EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` policy for this role in order for GitLab to manage the EKS cluster correctly. - -## Existing EKS cluster - -For information on adding an existing EKS cluster, see -[Existing Kubernetes cluster](add_remove_clusters.md#existing-kubernetes-cluster). - -### Create a default Storage Class - -Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes are not automatically fulfilled. As part -of Auto DevOps, the deployed PostgreSQL instance requests persistent storage, -and without a default storage class it cannot 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 PostgreSQL by setting the project variable -[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#cicd-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 isn't externally available outside of the cluster. - - - -GitLab creates a new pipeline, which begins to build, test, and deploy the app. - -After the pipeline has finished, your app runs in EKS, and is available -to users. Click on **CI/CD > Environments**. - - - -GitLab displays 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. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md new file mode 100644 index 00000000000..efd480fa3ce --- /dev/null +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -0,0 +1,224 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Add an existing Kubernetes cluster + +If you have an existing Kubernetes cluster, you can add it to a project, group, +or instance and benefit from the integration with GitLab. + +## Prerequisites + +See the prerequisites below to add existing clusters to GitLab. + +### All clusters + +To add any cluster to GitLab, you need: + +- Either a GitLab.com account or an account for a self-managed installation +running GitLab 12.5 or later. +- The Maintainer role for group-level and project-level clusters. +- Access to the Admin area for instance-level clusters. **(FREE SELF)** +- A Kubernetes cluster. +- Cluster administration access to the cluster with `kubectl`. + +You can host your cluster in [EKS](#eks-clusters), [GKE](#gke-clusters), +on premises, and with other providers. +To host them on premises and with other providers, +use either the EKS or GKE method to guide you through and enter your cluster's +settings manually. + +WARNING: +GitLab doesn't support `arm64` clusters. See the issue +[Helm Tiller fails to install on `arm64` cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) +for details. + +### EKS clusters + +To add an existing **EKS** cluster, you need: + +- An Amazon EKS cluster with worker nodes properly configured. +- `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) +for access to the EKS cluster. +- Ensure the token of the account has administrator privileges for the cluster. + +### GKE clusters + +To add an existing **GKE** cluster, you 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. + +## How to add an existing cluster + +<!-- (REVISE - BREAK INTO SMALLER STEPS) --> + +To add a Kubernetes cluster to your project, group, or instance: + +1. Navigate to your: + 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. + 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. + 1. **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. +1. Click **Add Kubernetes cluster**. +1. Click the **Add existing cluster** tab and fill in the details: + 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. + 1. **Environment scope** (required) - The + [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. + 1. **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. + For example, `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```shell + kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}' + ``` + + 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default. + 1. List the secrets with `kubectl get secrets`, and one should be named similar to + `default-token-xxxxx`. Copy that token name for use below. + 1. Get the certificate by running this command: + + ```shell + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + + If the command returns the entire certificate chain, you must copy the Root CA + certificate and any intermediate certificates at the bottom of the chain. + A chain file has following structure: + + ```plaintext + -----BEGIN MY CERTIFICATE----- + -----END MY CERTIFICATE----- + -----BEGIN INTERMEDIATE CERTIFICATE----- + -----END INTERMEDIATE CERTIFICATE----- + -----BEGIN INTERMEDIATE CERTIFICATE----- + -----END INTERMEDIATE CERTIFICATE----- + -----BEGIN ROOT CERTIFICATE----- + -----END ROOT CERTIFICATE----- + ``` + + 1. **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 + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```shell + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + You 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 administrator: + + ```shell + kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> + ``` + + NOTE: + Basic Authentication can be turned on and the password credentials + can be obtained using the Google Cloud Console. + + Output: + + ```shell + serviceaccount "gitlab" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab` service account: + + ```shell + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```plaintext + Name: gitlab-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab + 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. **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. **Project namespace** (optional) - You don't have to fill this in. By leaving + it blank, GitLab creates 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. Select the **Add Kubernetes cluster** button. + +After about 10 minutes, your cluster is ready. + +## 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 affects how GitLab interacts with the +cluster for certain operations. If you did *not* check the **RBAC-enabled cluster** +checkbox at creation time, GitLab assumes 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. + + + +WARNING: +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: + +```shell +kubectl create clusterrolebinding permissive-binding \ + --clusterrole=cluster-admin \ + --user=admin \ + --user=kubelet \ + --group=system:serviceaccounts +``` diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 9f0e5603785..a454b4dff99 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,7 +4,15 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding GKE clusters **(FREE)** +# GKE clusters (DEPRECATED) **(FREE)** + +> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. + +WARNING: +Use [Infrastrucure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. + +Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic +Kubernetes Service (EKS). GitLab supports adding new and existing GKE clusters. @@ -19,7 +27,12 @@ requirements are met: 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). -## New GKE cluster +## Add an existing GKE cluster + +If you already have a GKE cluster and want to integrate it with GitLab, +see how to [add an existing cluster](add_existing_cluster.md). + +## Create new GKE 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). @@ -30,13 +43,13 @@ Note the following: at the instance level. If that's not the case, ask your GitLab administrator to enable it. On GitLab.com, this is enabled. - 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](add_remove_clusters.md#rbac-cluster-resources) for + created by GitLab are RBAC-enabled. Take a look at the [RBAC section](cluster_access.md#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 is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to - set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions + set up an [initial service account](cluster_access.md). In [GitLab versions 11.10 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58208), the cluster creation process explicitly requests GKE to create clusters with basic authentication enabled and a client certificate. @@ -49,14 +62,14 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 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) to this cluster. + - **Environment scope** - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP console to host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). @@ -68,7 +81,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) 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. + See the [Managed clusters section](gitlab_managed_clusters.md) for more information. 1. Finally, click the **Create Kubernetes cluster** button. After a couple of minutes, your cluster is ready. @@ -81,8 +94,3 @@ You can choose to use Cloud Run for Anthos in place of installing Knative and Is separately after the cluster has been created. This means that Cloud Run (Knative), Istio, and HTTP Load Balancing are enabled on the cluster from the start, and cannot be installed or uninstalled. - -## Existing GKE cluster - -For information on adding an existing GKE cluster, see -[Existing Kubernetes cluster](add_remove_clusters.md#existing-kubernetes-cluster). diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 2ecbc4a2ff5..6cada5648cb 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,28 +4,16 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Add a cluster using cluster certificates **(FREE)** +# Add a cluster using cluster certificates (DEPRECATED) **(FREE)** -> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. WARNING: Creating a new cluster or adding an existing cluster to GitLab through the certificate-based method is deprecated and no longer recommended. Kubernetes cluster, similar to any other -infrastructure, should be created, updated, and maintained using [Infrastructure as Code](../../infrastructure/index.md). +infrastructure, should be created, updated, maintained using [Infrastructure as Code](../../infrastructure/index.md). GitLab is developing a built-in capability to create clusters with Terraform. -You can follow along in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6049). - -GitLab offers integrated cluster creation for the following Kubernetes providers: - -- Google Kubernetes Engine (GKE). -- Amazon Elastic Kubernetes Service (EKS). - -GitLab can also integrate with any standard Kubernetes provider, either on-premise or hosted. - -NOTE: -Watch the webcast [Scalable app deployment with GitLab and Google Cloud Platform](https://about.gitlab.com/webcast/scalable-app-deploy/) -and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) -in a few clicks. +You can follow along in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6049). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -35,351 +23,76 @@ accounts to get started with the GitLab integration with Google Kubernetes Engin [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) to apply for credit. -## Before you begin - -Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need: - -- GitLab itself. Either: - - A [GitLab.com account](https://about.gitlab.com/pricing/#gitlab-com). - - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version - 12.5 or later. This ensures the GitLab UI can be used for cluster creation. -- The following GitLab access: - - [Maintainer role for a project](../../permissions.md#project-members-permissions) for a - project-level cluster. - - [Maintainer role for a group](../../permissions.md#group-members-permissions) for a - group-level cluster. - - [Admin Area access](../../admin_area/index.md) for a self-managed instance-level - cluster. **(FREE SELF)** - -## Access controls - -> - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. - -When creating a cluster in GitLab, you are asked if you would like to create either: - -- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) - cluster, which is the GitLab default and recommended option. -- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. - -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. - -Helm also creates additional service accounts and other resources for each -installed application. Consult the documentation of the Helm charts for each application -for details. - -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 uses 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 charts | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm charts | -| 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` | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | +NOTE: +Watch the webcast [Scalable app deployment with GitLab and Google Cloud Platform](https://about.gitlab.com/webcast/scalable-app-deploy/) +and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) +in a few clicks. -The environment namespace `RoleBinding` was -[updated](https://gitlab.com/gitlab-org/gitlab/-/issues/31113) in GitLab 13.6 -to `admin` roleRef. Previously, the `edit` roleRef was used. +## Create new cluster -### ABAC cluster resources +> The certificate-based method for creating clusters from GitLab was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -GitLab creates the following resources for ABAC clusters. +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/index.md) +to **safely create your new cluster from GitLab**. -| 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 charts | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm charts | -| 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 | +The certificate-based method is **deprecated** and scheduled for removal in +GitLab 15.0. However, you can still use it until then. Through +this method, you can host your cluster in EKS, GKE, on premises, and with other +providers. To host them on premises and with other providers, +use either the EKS or GKE method to guide you through and enter your cluster's +settings manually: -### Security of runners +- [New cluster hosted on Google Kubernetes Engine (GKE)](add_eks_clusters.md). +- [New cluster hosted on Amazon Elastic Kubernetes Service (EKS)](add_gke_clusters.md). -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 run -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. +## Add existing cluster -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 already have a cluster and want to integrate it with GitLab, see how to +[add an existing cluster](add_existing_cluster.md). -If you don't want to use a runner in privileged mode, either: +## Configure your cluster -- Use shared runners on GitLab.com. They don't have this security issue. -- Set up your own runners using the configuration described at - [shared runners](../../gitlab_com/index.md#shared-runners) using - [`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). +As of GitLab 14.0, use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to configure your cluster. -## Create new cluster +## Disable a cluster -New clusters can be created using GitLab on Google Kubernetes Engine (GKE) or -Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level: +When you successfully create a new Kubernetes cluster or add an existing +one to GitLab, the cluster connection to GitLab becomes enabled. To disable it: -1. Navigate to your: - - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level - cluster. +1. Go to your: + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Integrate with a cluster certificate**. -1. Click the **Create new cluster** tab. -1. Click either **Amazon EKS** or **Google GKE**, and follow the instructions for your desired service: - - [Amazon EKS](add_eks_clusters.md#new-eks-cluster). - - [Google GKE](add_gke_clusters.md#creating-the-cluster-on-gke). - -After creating a cluster, you can [install runners](https://docs.gitlab.com/runner/install/kubernetes.html), -add a [cluster management project](../../clusters/management_project.md), -configure [Auto DevOps](../../../topics/autodevops/index.md), -or start [deploying right away](index.md#deploying-to-a-kubernetes-cluster). - -## Add existing cluster - -If you have an existing Kubernetes cluster, you can add it to a project, group, -or instance, and [install runners](https://docs.gitlab.com/runner/install/kubernetes.html) -on it (the cluster does not need to be added to GitLab first). - -After adding a cluster, you can add a [cluster management project](../../clusters/management_project.md), -configure [Auto DevOps](../../../topics/autodevops/index.md), -or start [deploying right away](index.md#deploying-to-a-kubernetes-cluster). - -### Existing Kubernetes cluster - -To add a Kubernetes cluster to your project, group, or instance: - -1. Navigate to your: - 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level - cluster. - 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. -1. Click the **Add existing cluster** tab and fill in the details: - 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. - 1. **Environment scope** (required) - The - [associated environment](index.md#setting-the-environment-scope) to this cluster. - 1. **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. - For example, `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - Get the API URL by running this command: - - ```shell - kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}' - ``` - - 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default. - 1. List the secrets with `kubectl get secrets`, and one should be named similar to - `default-token-xxxxx`. Copy that token name for use below. - 1. Get the certificate by running this command: - - ```shell - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - If the command returns the entire certificate chain, you must copy the Root CA - certificate and any intermediate certificates at the bottom of the chain. - A chain file has following structure: - - ```plaintext - -----BEGIN MY CERTIFICATE----- - -----END MY CERTIFICATE----- - -----BEGIN INTERMEDIATE CERTIFICATE----- - -----END INTERMEDIATE CERTIFICATE----- - -----BEGIN INTERMEDIATE CERTIFICATE----- - -----END INTERMEDIATE CERTIFICATE----- - -----BEGIN ROOT CERTIFICATE----- - -----END ROOT CERTIFICATE----- - ``` - - 1. **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 - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```shell - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - You 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 administrator: - - ```shell - kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> - ``` - - NOTE: - Basic Authentication can be turned on and the password credentials - can be obtained using the Google Cloud Console. - - Output: - - ```shell - serviceaccount "gitlab" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab` service account: - - ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```plaintext - Name: gitlab-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab - 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: - For GKE clusters, you 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. - - 1. **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. **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab creates 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 is ready. - -#### 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 affects how GitLab interacts with the -cluster for certain operations. If you did *not* check the **RBAC-enabled cluster** -checkbox at creation time, GitLab assumes 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. - - - -WARNING: -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: - -```shell -kubectl create clusterrolebinding permissive-binding \ - --clusterrole=cluster-admin \ - --user=admin \ - --user=kubelet \ - --group=system:serviceaccounts -``` + - **Menu >** **{admin}** **Admin >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. +1. Select the name of the cluster you want to disable. +1. Toggle **GitLab Integration** off (in gray). +1. Click **Save changes**. -## Enabling or disabling integration +## Remove a cluster -The Kubernetes cluster integration enables after you have successfully either created -a new cluster or added an existing one. To disable Kubernetes cluster integration: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26815) in GitLab 12.6, you can remove cluster integrations and resources. -1. Navigate to your: - - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level - cluster. - - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click on the name of the cluster. -1. Click the **GitLab Integration** toggle. -1. Click **Save changes**. +When you remove a cluster integration, you only remove the cluster relationship +to GitLab, not the cluster. To remove the cluster itself, visit your cluster's +GKE or EKS dashboard to do it from their UI or use `kubectl`. -## Removing integration +You need at least Maintainer [permissions](../../permissions.md) to your +project or group to remove the integration with GitLab. -To remove the Kubernetes cluster integration from your project, first navigate to the **Advanced Settings** tab of the cluster details page and either: +When removing a cluster integration, you have two options: -- Select **Remove integration**, to remove only the Kubernetes integration. -- [From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/26815), select - **Remove integration and resources**, to also remove all related GitLab cluster resources (for - example, namespaces, roles, and bindings) when removing the integration. +- **Remove integration**: remove only the Kubernetes integration. +- **Remove integration and resources**: remove the cluster integration and +all GitLab cluster-related resources such as namespaces, roles, and bindings. -When removing the cluster integration, note: +To remove the Kubernetes cluster integration: -- 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 or EKS dashboard, or using `kubectl`. +1. Go to your cluster details page. +1. Select the **Advanced Settings** tab. +1. Select either **Remove integration** or **Remove integration and resources**. -## Learn more +## Access controls -To learn more on automatically deploying your applications, -read about [Auto DevOps](../../../topics/autodevops/index.md). +See [cluster access controls (RBAC or ABAC)](cluster_access.md). ## Troubleshooting diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md new file mode 100644 index 00000000000..713a60b2dd0 --- /dev/null +++ b/doc/user/project/clusters/cluster_access.md @@ -0,0 +1,88 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Cluster access controls (RBAC or ABAC) + +> Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. + +When creating a cluster in GitLab, you are asked if you would like to create either: + +- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) + cluster, which is the GitLab default and recommended option. +- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. + +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. + +Helm also creates additional service accounts and other resources for each +installed application. Consult the documentation of the Helm charts for each application +for details. + +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 uses 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 | +| 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` | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +The environment namespace `RoleBinding` was +[updated](https://gitlab.com/gitlab-org/gitlab/-/issues/31113) in GitLab 13.6 +to `admin` roleRef. Previously, the `edit` roleRef was used. + +## 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 | +| 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 runners + +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 run +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 a runner in privileged mode, either: + +- Use shared runners on GitLab.com. They don't have this security issue. +- Set up your own runners using the configuration described at +[shared runners](../../gitlab_com/index.md#shared-runners) using +[`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md new file mode 100644 index 00000000000..fdd65d70242 --- /dev/null +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -0,0 +1,141 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Deploy to a Kubernetes cluster + +A Kubernetes cluster can be the destination for a deployment job. If + +- The cluster is integrated with GitLab, special + [deployment variables](#deployment-variables) are made available to your job + and configuration is not required. You can immediately begin interacting with + the cluster from your jobs using tools such as `kubectl` or `helm`. +- You don't use the GitLab cluster integration, you can still deploy to your + cluster. However, you must configure Kubernetes tools yourself + using [CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) + before you can interact with the cluster from your jobs. + +## Deployment variables + +Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) named +[`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the +following command in your deployment job script, for Kubernetes to access the registry: + +- Using Kubernetes 1.18+: + + ```shell + kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run=client | kubectl apply -f - + ``` + +- Using Kubernetes <1.18: + + ```shell + kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - + ``` + +The Kubernetes cluster integration exposes these +[deployment variables](../../../ci/variables/index.md#deployment-variables) in the +GitLab CI/CD build environment to deployment jobs. Deployment jobs have +[defined a target environment](../../../ci/environments/index.md). + +| Deployment Variable | Description | +|----------------------------|-------------| +| `KUBE_URL` | Equal to the API URL. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](cluster_access.md). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `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. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | +| `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 configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | +| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](gitlab_managed_clusters.md#base-domain) for more information. | + +## Custom namespace + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. +> - An option to use project-wide namespaces [was added](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) in GitLab 13.5. + +The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace +to deployment jobs. It defaults to using project-environment specific namespaces +of the form `<prefix>-<environment>`, where `<prefix>` is of the form +`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables). + +You can customize the deployment namespace in a few ways: + +- You can choose between a **namespace per [environment](../../../ci/environments/index.md)** + or a **namespace per project**. A namespace per environment is the default and recommended + setting, as it prevents the mixing of resources between production and non-production environments. +- When using a project-level cluster, you can additionally customize the namespace prefix. + When using namespace-per-environment, the deployment namespace is `<prefix>-<environment>`, + but otherwise just `<prefix>`. +- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, + but the user is responsible for ensuring its existence. You can fully customize + this value using + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments) + in `.gitlab-ci.yml`. + +When you customize the namespace, existing environments remain linked to their current +namespaces until you [clear the cluster cache](gitlab_managed_clusters.md#clearing-the-cluster-cache). + +### Protecting credentials + +By default, anyone who can create a deployment job can access any CI/CD variable in +an environment's deployment job. This includes `KUBECONFIG`, which gives access to +any secret available to the associated service account in your cluster. +To keep your production credentials safe, consider using +[protected environments](../../../ci/environments/protected_environments.md), +combined with *one* of the following: + +- A GitLab-managed cluster and namespace per environment. +- An environment-scoped cluster per protected environment. The same cluster + can be added multiple times with multiple restricted service accounts. + +## Web terminals for Kubernetes clusters + +> Introduced in GitLab 8.15. + +The Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) +support to your [environments](../../../ci/environments/index.md). This is based +on the `exec` functionality found in Docker and Kubernetes, so you get a new +shell session in your existing containers. To use this integration, you +should deploy to Kubernetes using the deployment variables above, ensuring any +deployments, replica sets, and pods are annotated with: + +- `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` +- `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` + +`$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of +the CI/CD variables. + +You must be the project owner or have `maintainer` permissions to use terminals. +Support is limited to the first container in the first pod of your environment. + +## Troubleshooting + +Before the deployment jobs starts, GitLab creates the following specifically for +the deployment job: + +- A namespace. +- A service account. + +However, sometimes GitLab cannot create them. In such instances, your job can fail with the message: + +```plaintext +This job failed because the necessary resources were not successfully created. +``` + +To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). + +Reasons for failure include: + +- The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges required by GitLab. +- Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching + [`environment:name`](../../../ci/environments/index.md). If your job has no + `environment:name` set, the Kubernetes credentials are not passed to it. + +NOTE: +Project-level clusters upgraded from GitLab 12.0 or older may be configured +in a way that causes this error. Ensure you deselect the +[GitLab-managed cluster](gitlab_managed_clusters.md) option if you want to manage +namespaces and service accounts yourself. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md new file mode 100644 index 00000000000..77921ec1dff --- /dev/null +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -0,0 +1,102 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab-managed clusters + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. +> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. + +You can choose to allow GitLab to manage your cluster for you. If your cluster +is managed by GitLab, resources for your projects are automatically created. See +the [Access controls](add_remove_clusters.md#access-controls) section for +details about the created resources. + +If you choose to manage your own cluster, project-specific resources aren't created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must +explicitly provide the `KUBE_NAMESPACE` [deployment variable](deploy_to_cluster.md#deployment-variables) +for your deployment jobs to use. Otherwise, a namespace is created for you. + +WARNING: +Be aware that manually managing resources that have been created by GitLab, like +namespaces and service accounts, can cause unexpected errors. If this occurs, try +[clearing the cluster cache](#clearing-the-cluster-cache). + +## Clearing the cluster cache + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. + +If you allow GitLab to manage your cluster, GitLab stores a cached +version of the namespaces and service accounts it creates for your projects. If you +modify these resources in your cluster manually, this cache can fall out of sync with +your cluster. This can cause deployment jobs to fail. + +To clear the cache: + +1. Navigate to your project's **Infrastructure > Kubernetes clusters** page, and select your cluster. +1. Expand the **Advanced settings** section. +1. Click **Clear cluster cache**. + +## Base domain + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. + +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable. +If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different +stages. For example, Auto Review Apps and Auto Deploy. + +The domain should have a wildcard DNS configured to the Ingress IP address. +You can either: + +- Create an `A` record that points to the Ingress IP address with your domain provider. +- Enter a wildcard DNS address using a service such as `nip.io` or `xip.io`. For example, `192.168.1.1.xip.io`. + +To determine the external Ingress IP address, or external Ingress hostname: + +- *If the cluster is on GKE*: + 1. Click the **Google Kubernetes Engine** link in the **Advanced settings**, + or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/). + 1. Select the proper project and cluster. + 1. Click **Connect** + 1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**. + +- *If the cluster is not on GKE*: Follow the specific instructions for your + Kubernetes provider to configure `kubectl` with the right credentials. + The output of the following examples show the external endpoint of your + cluster. This information can then be used to set up DNS entries and forwarding + rules that allow external access to your deployed applications. + +Depending an your Ingress, the external IP address can be retrieved in various ways. +This list provides a generic solution, and some GitLab-specific approaches: + +- In general, you can list the IP addresses of all load balancers by running: + + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` + +- If you installed Ingress using the **Applications**, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` + +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` + + If you use EKS, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which incurs additional AWS costs. + +- Istio/Knative uses a different command. Run: + + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + +If you see a trailing `%` on some Kubernetes versions, do not include it. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 8dd8ed52dd7..a0efea267f0 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,6 +1,6 @@ --- -stage: Monitor -group: Monitor +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -12,35 +12,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in > GitLab 11.11 for [instances](../../instance/clusters/index.md). -Using the GitLab project Kubernetes integration, you can: - -- Use [Review Apps](../../../ci/review_apps/index.md). -- Run [pipelines](../../../ci/pipelines/index.md). -- [Deploy](#deploying-to-a-kubernetes-cluster) your applications. -- Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). -- Use it with [Auto DevOps](#auto-devops). -- Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards). -- Use [Canary Deployments](#canary-deployments). **(PREMIUM)** -- Use [deployment variables](#deployment-variables). -- Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). -- View [Logs](#viewing-pod-logs). -- Run serverless workloads on [Kubernetes with Knative](serverless/index.md). +We offer extensive integrations to help you connect and manage your Kubernetes clusters from GitLab. -Besides integration at the project level, Kubernetes clusters can also be -integrated at the [group level](../../group/clusters/index.md) or -[GitLab instance level](../../instance/clusters/index.md). +Read through this document to get started. -To view your project level Kubernetes clusters, navigate to **Infrastructure > Kubernetes clusters** -from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters) -and view information about your existing clusters, such as: +## Clusters infrastructure -- Nodes count. -- Rough estimates of memory and CPU usage. +Use [Infrastructure as Code](../../infrastructure) to create and manage your clusters with the GitLab integration with Terraform. + +## Benefit from the GitLab-Kubernetes integration + +Using the GitLab-Kubernetes integration, you can benefit of GitLab +features such as: -## Setting up +- Create [CI/CD Pipelines](../../../ci/pipelines/index.md) to build, test, and deploy to your cluster. +- Use [Auto DevOps](#auto-devops) to automate the CI/CD process. +- Use [role-based or attribute-based access controls](cluster_access.md). +- Run serverless workloads on [Kubernetes with Knative](serverless/index.md). +- Connect GitLab to in-cluster applications using [cluster integrations](../../clusters/integrations.md). +- Use [Deploy Boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. +- Use [Canary deployments](../canary_deployments.md) to update only a portion of your fleet with the latest version of your application. +- View your [Kubernetes podlogs](kubernetes_pod_logs.md) directly in GitLab. +- Connect to your cluster through GitLab [web terminals](deploy_to_cluster.md#web-terminals-for-kubernetes-clusters). -### Supported cluster versions +## Supported cluster versions GitLab is committed to support at least two production-ready Kubernetes minor versions at any given time. We regularly review the versions we support, and @@ -48,7 +43,7 @@ provide a three-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of: - The versions supported by major managed Kubernetes providers. -- The versions [supported by the Kubernetes community](https://kubernetes.io/docs/setup/release/version-skew-policy/#supported-versions). +- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time: @@ -61,88 +56,34 @@ Kubernetes version to any supported version at any time: Some GitLab features may support versions outside the range provided here. -NOTE: -[GKE Cluster creation](add_remove_clusters.md#create-new-cluster) by GitLab is currently not supported for Kubernetes 1.19+. For these versions you can create the cluster through GCP, then [Add existing cluster](add_remove_clusters.md#add-existing-cluster). See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331922) for more information. - -### Adding and removing clusters - -See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how -to: - -- Create a cluster in Google Cloud Platform (GCP) or Amazon Elastic Kubernetes Service - (EKS) using the GitLab UI. -- Add an integration to an existing cluster from any Kubernetes platform. - -### Multiple Kubernetes clusters - -> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. +## Add and remove clusters -You can associate more than one Kubernetes cluster to your -project. That way you can have different clusters for different environments, -like development, staging, production, and so on. -Add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that -differentiates the new cluster from the rest. +You can create new or add existing clusters to GitLab: -#### Setting the environment scope +- On the project-level, to have a cluster dedicated to a project. +- On the [group level](../../group/clusters/index.md), to use the same cluster across multiple projects within your group. +- On the [instance level](../../instance/clusters/index.md), to use the same cluster across multiple groups and projects. **(FREE SELF)** -When adding more than one Kubernetes cluster to your project, you need to differentiate -them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific CI/CD variables](../../../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) work. +To create new clusters, use one of the following methods: -The default environment scope is `*`, which means all jobs, regardless of their -environment, use that cluster. Each scope can be used only by a single cluster -in a project, and a validation error occurs if otherwise. Also, jobs that don't -have an environment keyword set can't access any cluster. +- [Infrastructure as Code](../../infrastructure/index.md) (**recommended**). +- [Cluster certificates](add_remove_clusters.md) (**deprecated**). -For example, let's say the following Kubernetes clusters exist in a project: +You can also [add existing clusters](add_existing_cluster.md) to GitLab. -| Cluster | Environment scope | -| ----------- | ----------------- | -| Development | `*` | -| Production | `production` | +## View your clusters -And the following environments are set in -[`.gitlab-ci.yml`](../../../ci/yaml/README.md): - -```yaml -stages: - - test - - deploy - -test: - stage: test - script: sh test - -deploy to staging: - stage: deploy - script: make deploy - environment: - name: staging - url: https://staging.example.com/ - -deploy to production: - stage: deploy - script: make deploy - environment: - name: production - url: https://example.com/ -``` - -The results: +To view your project-level Kubernetes clusters, to go **Infrastructure > Kubernetes clusters** +from your project. On this page, you can add a new cluster +and view information about your existing clusters, such as: -- The Development cluster details are available in the `deploy to staging` - job. -- The production cluster details are available in the `deploy to production` - job. -- No cluster details are available in the `test` job because it doesn't - define any environment. +- Nodes count. +- Rough estimates of memory and CPU usage. ## Configuring your Kubernetes cluster -After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers -important considerations for configuring Kubernetes clusters with GitLab. +Use the [GitLab Kubernetes Agent](../../clusters/agent/index.md) to safely +configure your clusters. Otherwise, there are [security implications](#security-implications). ### Security implications @@ -155,103 +96,15 @@ 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. -### GitLab-managed clusters - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. -> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. - -You can choose to allow GitLab to manage your cluster for you. If your cluster -is managed by GitLab, resources for your projects are automatically created. See -the [Access controls](add_remove_clusters.md#access-controls) section for -details about the created resources. - -If you choose to manage your own cluster, project-specific resources aren't created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must -explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -for your deployment jobs to use. Otherwise, a namespace is created for you. - -#### Important notes - -Be aware that manually managing resources that have been created by GitLab, like -namespaces and service accounts, can cause unexpected errors. If this occurs, try -[clearing the cluster cache](#clearing-the-cluster-cache). - -#### Clearing the cluster cache - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. - -If you allow GitLab to manage your cluster, GitLab stores a cached -version of the namespaces and service accounts it creates for your projects. If you -modify these resources in your cluster manually, this cache can fall out of sync with -your cluster. This can cause deployment jobs to fail. - -To clear the cache: - -1. Navigate to your project's **Infrastructure > Kubernetes clusters** page, and select your cluster. -1. Expand the **Advanced settings** section. -1. Click **Clear cluster cache**. - -### Base domain - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. - -Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable. -If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different -stages. For example, Auto Review Apps and Auto Deploy. - -The domain should have a wildcard DNS configured to the Ingress IP address. -You can either: - -- Create an `A` record that points to the Ingress IP address with your domain provider. -- Enter a wildcard DNS address using a service such as `nip.io` or `xip.io`. For example, `192.168.1.1.xip.io`. - -To determine the external Ingress IP address, or external Ingress hostname: - -- *If the cluster is on GKE*: - 1. Click the **Google Kubernetes Engine** link in the **Advanced settings**, - or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/). - 1. Select the proper project and cluster. - 1. Click **Connect** - 1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**. - -- *If the cluster is not on GKE*: Follow the specific instructions for your - Kubernetes provider to configure `kubectl` with the right credentials. - The output of the following examples show the external endpoint of your - cluster. This information can then be used to set up DNS entries and forwarding - rules that allow external access to your deployed applications. - -Depending an your Ingress, the external IP address can be retrieved in various ways. -This list provides a generic solution, and some GitLab-specific approaches: - -- In general, you can list the IP addresses of all load balancers by running: - - ```shell - kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' - ``` - -- If you installed Ingress using the **Applications**, run: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' - ``` - -- Some Kubernetes clusters return a hostname instead, like - [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' - ``` - - If you use EKS, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) - is also created, which incurs additional AWS costs. +## Multiple Kubernetes clusters -- Istio/Knative uses a different command. Run: +See how to associate [multiple Kubernetes clusters](multiple_kubernetes_clusters.md) +with your GitLab project. - ```shell - kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` +## Cluster integrations -If you see a trailing `%` on some Kubernetes versions, do not include it. +See the available [cluster integrations](../../clusters/integrations.md) +to integrate third-party applications with your clusters through GitLab. ## Cluster management project @@ -259,180 +112,18 @@ Attach a [Cluster management project](../../clusters/management_project.md) to your cluster to manage shared resources requiring `cluster-admin` privileges for installation, such as an Ingress controller. -## Auto DevOps +## GitLab-managed clusters -Auto DevOps automatically detects, builds, tests, deploys, and monitors your -applications. +See how to allow [GitLab to manage your cluster for you](gitlab_managed_clusters.md). -To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) the Kubernetes project integration must be enabled. However, -Kubernetes clusters can be used without Auto DevOps. +## Auto DevOps -[Read more about Auto DevOps](../../../topics/autodevops/index.md). +You can use [Auto DevOps](../../../topics/autodevops/index.md) to automatically +detect, build, test, deploy, and monitor your applications. ## Deploying to a Kubernetes cluster -A Kubernetes cluster can be the destination for a deployment job. If - -- The cluster is integrated with GitLab, special - [deployment variables](#deployment-variables) are made available to your job - and configuration is not required. You can immediately begin interacting with - the cluster from your jobs using tools such as `kubectl` or `helm`. -- You don't use the GitLab cluster integration, you can still deploy to your - cluster. However, you must configure Kubernetes tools yourself - using [CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables) - before you can interact with the cluster from your jobs. - -### Deployment variables - -Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) named -[`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the -following command in your deployment job script, for Kubernetes to access the registry: - -- Using Kubernetes 1.18+: - - ```shell - kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run=client | kubectl apply -f - - ``` - -- Using Kubernetes <1.18: - - ```shell - kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - - ``` - -The Kubernetes cluster integration exposes these -[deployment variables](../../../ci/variables/README.md#deployment-variables) in the -GitLab CI/CD build environment to deployment jobs. Deployment jobs have -[defined a target environment](../../../ci/environments/index.md). - -| Deployment Variable | Description | -|----------------------------|-------------| -| `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | -| `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. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | -| `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 configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | -| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | - -### Custom namespace - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. -> - An option to use project-wide namespaces [was added](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) in GitLab 13.5. - -The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace -to deployment jobs. It defaults to using project-environment specific namespaces -of the form `<prefix>-<environment>`, where `<prefix>` is of the form -`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables). - -You can customize the deployment namespace in a few ways: - -- You can choose between a **namespace per [environment](../../../ci/environments/index.md)** - or a **namespace per project**. A namespace per environment is the default and recommended - setting, as it prevents the mixing of resources between production and non-production environments. -- When using a project-level cluster, you can additionally customize the namespace prefix. - When using namespace-per-environment, the deployment namespace is `<prefix>-<environment>`, - but otherwise just `<prefix>`. -- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, - but the user is responsible for ensuring its existence. You can fully customize - this value using - [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments) - in `.gitlab-ci.yml`. - -When you customize the namespace, existing environments remain linked to their current -namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). - -#### Protecting credentials - -By default, anyone who can create a deployment job can access any CI/CD variable in -an environment's deployment job. This includes `KUBECONFIG`, which gives access to -any secret available to the associated service account in your cluster. -To keep your production credentials safe, consider using -[protected environments](../../../ci/environments/protected_environments.md), -combined with *one* of the following: - -- A GitLab-managed cluster and namespace per environment. -- An environment-scoped cluster per protected environment. The same cluster - can be added multiple times with multiple restricted service accounts. - -### Integrations - -#### Canary Deployments - -Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -and visualize your canary deployments right inside the Deploy Board, without -the need to leave GitLab. - -[Read more about Canary Deployments](../canary_deployments.md) - -#### Deploy Boards - -GitLab Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes. -They display the status of the pods in the deployment. Developers and other -teammates can view the progress and status of a rollout, pod by pod, in the -workflow they already use without any need to access Kubernetes. - -[Read more about Deploy Boards](../deploy_boards.md) - -#### Viewing pod logs - -GitLab enables you to view the logs of running pods in connected Kubernetes -clusters. By displaying the logs directly in GitLab, developers can avoid having -to manage console tools or jump to a different interface. - -[Read more about Kubernetes logs](kubernetes_pod_logs.md) - -#### Web terminals - -> Introduced in GitLab 8.15. - -When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) -support to your [environments](../../../ci/environments/index.md). This is based -on the `exec` functionality found in Docker and Kubernetes, so you get a new -shell session in your existing containers. To use this integration, you -should deploy to Kubernetes using the deployment variables above, ensuring any -deployments, replica sets, and pods are annotated with: - -- `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` -- `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` - -`$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of -the CI/CD variables. - -You must be the project owner or have `maintainer` permissions to use terminals. -Support is limited to the first container in the first pod of your environment. - -### Troubleshooting - -Before the deployment jobs starts, GitLab creates the following specifically for -the deployment job: - -- A namespace. -- A service account. - -However, sometimes GitLab can not create them. In such instances, your job can fail with the message: - -```plaintext -This job failed because the necessary resources were not successfully created. -``` - -To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). - -Reasons for failure include: - -- The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges required by GitLab. -- Missing `KUBECONFIG` or `KUBE_TOKEN` deployment variables. To be passed to your job, they must have a matching - [`environment:name`](../../../ci/environments/index.md). If your job has no - `environment:name` set, the Kubernetes credentials are not passed to it. - -NOTE: -Project-level clusters upgraded from GitLab 12.0 or older may be configured -in a way that causes this error. Ensure you deselect the -[GitLab-managed cluster](#gitlab-managed-clusters) option if you want to manage -namespaces and service accounts yourself. +See how to [deploy to your Kubernetes cluster](deploy_to_cluster.md) from GitLab. ## Monitoring your Kubernetes cluster diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md new file mode 100644 index 00000000000..e2eae011b8c --- /dev/null +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -0,0 +1,71 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Multiple Kubernetes clusters for a single project + +> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. + +You can associate more than one Kubernetes cluster to your +project. That way you can have different clusters for different environments, +like development, staging, production, and so on. +Add another cluster, like you did the first time, and make sure to +[set an environment scope](#setting-the-environment-scope) that +differentiates the new cluster from the rest. + +## Setting the environment scope + +When adding more than one Kubernetes cluster to your project, you need to differentiate +them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the +[environment-specific CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) work. + +The default environment scope is `*`, which means all jobs, regardless of their +environment, use that cluster. Each scope can be used only by a single cluster +in a project, and a validation error occurs if otherwise. Also, jobs that don't +have an environment keyword set can't access any cluster. + +For example, let's say the following Kubernetes clusters exist in a project: + +| Cluster | Environment scope | +| ----------- | ----------------- | +| Development | `*` | +| Production | `production` | + +And the following environments are set in +[`.gitlab-ci.yml`](../../../ci/yaml/index.md): + +```yaml +stages: + - test + - deploy + +test: + stage: test + script: sh test + +deploy to staging: + stage: deploy + script: make deploy + environment: + name: staging + url: https://staging.example.com/ + +deploy to production: + stage: deploy + script: make deploy + environment: + name: production + url: https://example.com/ +``` + +The results: + +- The Development cluster details are available in the `deploy to staging` + job. +- The production cluster details are available in the `deploy to production` + job. +- No cluster details are available in the `test` job because it doesn't + define any environment. diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index ebcd56078ae..466bcb7916f 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -20,7 +20,7 @@ The following steps are recommended to install and use Container Host Security t 1. Install and configure an Ingress node: - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) + - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../gitlab_managed_clusters.md#base-domain) into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes cluster. @@ -50,7 +50,7 @@ kubectl -n gitlab-managed-apps logs -l app=falco Your CI/CD pipeline may occasionally fail or have trouble connecting to the cluster. Here are some initial troubleshooting steps that resolve the most common problems: -1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache) +1. [Clear the cluster cache](../../gitlab_managed_clusters.md#clearing-the-cluster-cache) 1. If things still aren't working, a more assertive set of actions may help get things back to a good state: diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 33aefec224a..62010bb7802 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -20,20 +20,114 @@ The following steps are recommended to install and use Container Network Securit 1. Install and configure an Ingress node: - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) + - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../gitlab_managed_clusters.md#base-domain) into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes cluster. -1. [Install and configure Cilium](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd). +1. [Install and configure Cilium](#use-the-cluster-management-template-to-install-cilium). 1. Be sure to restart all pods that were running before Cilium was installed by running this command in your cluster: `kubectl get pods --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HOSTNETWORK:.spec.hostNetwork --no-headers=true | grep '<none>' | awk '{print "-n "$1" "$2}' | xargs -L 1 -r kubectl delete pod` + You can skip this step if `nodeinit.restartPods` is set to `true` on your Helm chart. + It's possible to install and manage Cilium in other ways. For example, you could use the GitLab Helm chart to install Cilium manually in a Kubernetes cluster, and then connect it back to GitLab. However, such methods aren't documented or officially supported by GitLab. +### Use the Cluster Management template to install Cilium + +[Cilium](https://cilium.io/) is a networking plug-in for Kubernetes that you can use to implement +support for [`NetworkPolicy`](https://kubernetes.io/docs/concepts/services-networking/network-policies/) +resources. For more information, see [Network Policies](../../../../../topics/autodevops/stages.md#network-policy). + +You can use the [Cluster Management Project Template](../../../../clusters/management_project_template.md) +to install Cilium in your Kubernetes cluster. + +1. In your cluster management project, go to `helmfile.yaml` and uncomment `- path: applications/cilium/helmfile.yaml`. +1. In `applications/cilium/helmfile.yaml`, set `clusterType` to either `gke` or `eks` based on which Kubernetes provider your are using. + + ```yaml + environments: + default: + values: + # Set to "gke" or "eks" based on your cluster type + - clusterType: "" + ``` + +1. Merge or push these changes to the default branch of your cluster management project, +and [GitLab CI/CD](../../../../../ci/README.md) will automatically install Cilium. + +WARNING: +Installation and removal of the Cilium requires a **manual** +[restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-helm/#restart-unmanaged-pods) +of all affected pods in all namespaces to ensure that they are +[managed](https://docs.cilium.io/en/stable/operations/troubleshooting/#ensure-managed-pod) +by the correct networking plug-in. When Hubble is enabled, its related pod might require a +restart depending on whether it started prior to Cilium. For more information, see +[Failed Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#failed-deployment) +in the Kubernetes docs. + +NOTE: +Major upgrades might require additional setup steps. For more information, see +the official [upgrade guide](https://docs.cilium.io/en/stable/operations/upgrade/). + +Support for installing the Cilium application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). + +### Configure the Cilium Helm chart + +You can customize Cilium's Helm variables by editing the `applications/cilium/values.yaml` +file in your cluster management project. Refer to the [Cilium Helm reference](https://docs.cilium.io/en/stable/helm-reference/) +for the available configuration options. + +By default, Cilium's +[audit mode](https://docs.cilium.io/en/stable/gettingstarted/policy-creation/#enable-policy-audit-mode) +is enabled. In audit mode, Cilium doesn't drop disallowed packets. You +can use `policy-verdict` log to observe policy-related decisions. You +can disable audit mode by setting `policyAuditMode: false` in +`applications/cilium/values.yaml`. + +The Cilium monitor log for traffic is logged out by the +`cilium-monitor` sidecar container. You can check these logs with the following command: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor +``` + +You can disable the monitor log in `application/cilium/values.yaml`: + +```yaml +monitor: + enabled: false +``` + +The [Hubble](https://github.com/cilium/hubble) monitoring daemon is enabled by default +and it's set to collect per namespace flow metrics. This metrics are accessible on the +[Threat Monitoring](../../../../application_security/threat_monitoring/index.md) +dashboard. You can disable Hubble by adding the following to +`applications/cilium/values.yaml`: + +```yaml +hubble: + enabled: false +``` + +You can also adjust Helm values for Hubble by using +`applications/cilium/values.yaml`: + +```yaml +hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' +``` + ## Managing Network Policies Managing NetworkPolicies through GitLab is advantageous over managing the policies in Kubernetes @@ -62,16 +156,14 @@ editor. To view statistics for Container Network Security, you must follow the installation steps above and configure GitLab integration with Prometheus. Also, if you use custom Helm values for Cilium, you must enable Hubble with flow metrics for each namespace by adding the following lines to -your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd): -your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd): +your [Cilium values](#use-the-cluster-management-template-to-install-cilium): ```yaml -global: - hubble: - enabled: true - metrics: - enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' +hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` Additional information about the statistics page is available in the @@ -97,15 +189,14 @@ kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor By default, Cilium is installed in Audit mode only, meaning that NetworkPolicies log policy violations but don't block any traffic. To set Cilium to Blocking mode, you must add the following -lines to the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster management project: +lines to the `applications/cilium/values.yaml` file in your cluster management project: ```yaml config: policyAuditMode: false -agent: - monitor: - eventTypes: ["drop"] +monitor: + eventTypes: ["drop"] ``` ### Traffic is not being allowed as expected @@ -120,7 +211,7 @@ traffic that you want to allow in the node. Occasionally, your CI/CD pipeline may fail or have trouble connecting to the cluster. Here are some initial troubleshooting steps that resolve the most common problems: -1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache). +1. [Clear the cluster cache](../../gitlab_managed_clusters.md#clearing-the-cluster-cache). 1. If things still aren't working, a more assertive set of actions may help get things back into a good state: diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 5d6fb8252bb..6eafb4530d3 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -134,7 +134,7 @@ This example code does the following: #### Setting up your AWS credentials with your GitLab account In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**. -For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#custom-variables-validated-by-gitlab). +For more information please see [Create a custom variable in the UI](../../../../ci/variables/index.md#custom-variables-validated-by-gitlab). The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. @@ -381,7 +381,7 @@ control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. ### Crafting the `.gitlab-ci.yml` file -In a [`.gitlab-ci.yml`](../../../../ci/yaml/README.md) file in the root of your project, +In a [`.gitlab-ci.yml`](../../../../ci/yaml/index.md) file in the root of your project, add the following and replace `<S3_bucket_name>` with the name of the S3 bucket where you want to store your package: diff --git a/doc/user/project/clusters/serverless/img/function-details-loaded.png b/doc/user/project/clusters/serverless/img/function-details-loaded.png Binary files differdeleted file mode 100644 index 2f0d61f8032..00000000000 --- a/doc/user/project/clusters/serverless/img/function-details-loaded.png +++ /dev/null diff --git a/doc/user/project/clusters/serverless/img/function-details-loaded_v14_0.png b/doc/user/project/clusters/serverless/img/function-details-loaded_v14_0.png Binary files differnew file mode 100644 index 00000000000..a19d236fc39 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/function-details-loaded_v14_0.png diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png Binary files differdeleted file mode 100644 index 8dce3cb1f70..00000000000 --- a/doc/user/project/clusters/serverless/img/serverless-page.png +++ /dev/null diff --git a/doc/user/project/clusters/serverless/img/serverless-page_v14_0.png b/doc/user/project/clusters/serverless/img/serverless-page_v14_0.png Binary files differnew file mode 100644 index 00000000000..f88eb4bdcd2 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/serverless-page_v14_0.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index e4ac1eabffe..ec22f71157f 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -322,7 +322,7 @@ being executed which deploys each function as a Knative service. After the deploy stage has finished, additional details for the function display under **Infrastructure > Serverless platform**. - + This page contains all functions available for the project, the description for accessing the function, and, if available, the function's runtime information. @@ -364,7 +364,7 @@ kubectl create secret generic my-secrets -n "$KUBE_NAMESPACE" --from-literal MY_ #### Part of deployment job -You can extend your `.gitlab-ci.yml` to create the secrets during deployment using the [CI/CD variables](../../../../ci/variables/README.md) +You can extend your `.gitlab-ci.yml` to create the secrets during deployment using the [CI/CD variables](../../../../ci/variables/index.md) stored securely under your GitLab project. ```yaml @@ -463,7 +463,7 @@ Go to the **Infrastructure > Serverless platform** page to see the final URL of On the same page as above, click on one of the function rows to bring up the function details page. - + The pod count gives you the number of pods running the serverless function instances on a given cluster. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index ea7bcce99c1..2a60c06814b 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -11,56 +11,56 @@ type: reference > - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. > - Moved to GitLab Premium in 13.9. -## Introduction +Code Owners define who owns specific files or paths in a repository. +You can require that Code Owners approve a merge request before it's merged. -When contributing to a project, it can often be difficult -to find out who should review or approve merge requests. -Additionally, if you have a question over a specific file or -code block, it may be difficult to know who to find the answer from. +Code Owners help you determine who should review or approve merge requests. +If you have a question about a file or feature, Code Owners +can help you find someone who knows the answer. -The GitLab Code Owners feature defines who owns specific -files or paths in a repository, allowing other users to understand -who is responsible for each file or path. +If you don't want to use Code Owners for approvals, you can +[configure rules](merge_requests/approvals/rules.md) instead. -As an alternative to using Code Owners for approvals, you can instead -[configure rules](merge_requests/approvals/rules.md). +## Set up Code Owners -## Why is this useful? +You can specify users or [shared groups](members/share_project_with_groups.md) +that are responsible for specific files and directories in a repository. -Code Owners allows for a version controlled, single source of -truth file outlining the exact GitLab users or groups that -own certain files or paths in a repository. In larger organizations -or popular open source projects, Code Owners can help you understand -who to contact if you have a question about a specific portion of -the codebase. Code Owners can also streamline the merge request approval -process, identifying the most relevant reviewers and approvers for a -given change. +To set up Code Owners: -## How to set up Code Owners +1. Choose the location where you want to specify Code Owners: + - In the root directory of the repository + - In the `.gitlab/` directory + - In the `docs/` directory -You can use a `CODEOWNERS` file to specify users or -[shared groups](members/share_project_with_groups.md) -that are responsible for specific files and directories in a repository. +1. In that location, create a file named `CODEOWNERS`. + +1. In the file, enter text that follows one of these patterns: + + ```plaintext + # A member as Code Owner of a file + filename @username + + # A member as Code Owner of a directory + directory @username -You can choose to add the `CODEOWNERS` file in three places: + # All group members as Code Owners of a file + filename @groupname -- To the root directory of the repository -- Inside the `.gitlab/` directory -- Inside the `docs/` directory + # All group members as Code Owners of a directory + directory @groupname + ``` -The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners -in a feature branch, the changes aren't valid in the main branch until the feature branch is merged. +The Code Owners are displayed in the UI by the files or directory they apply to. +These owners apply to this branch only. When you add new files to the repository, +you should update the `CODEOWNERS` file. -If you introduce new files to your repository and you want to identify the code owners for that file, -you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same -branch), GitLab counts the owners as soon as the branch is merged. If -you don't, you can do that later, but your new files don't belong to anyone until you update your -`CODEOWNERS` file in the TARGET branch. +## When a file matches multiple `CODEOWNERS` entries When a file matches multiple entries in the `CODEOWNERS` file, -the users from last pattern matching the file are displayed on the -blob page of the given file. For example, you have the following -`CODEOWNERS` file: +the users from last pattern matching the file are used. + +For example, in the following `CODEOWNERS` file: ```plaintext README.md @user1 @@ -77,7 +77,7 @@ After you've added Code Owners to a project, you can configure it to be used for merge request approvals: - As [merge request eligible approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). -- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** +- As required approvers for [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch). **(PREMIUM)** Developer or higher [permissions](../permissions.md) are required to approve a merge request. @@ -93,11 +93,11 @@ without using [Approval Rules](merge_requests/approvals/rules.md): 1. Create the file in one of the three locations specified above. 1. Set the code owners as required approvers for - [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). -1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) + [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch). +1. Use [the syntax of Code Owners files](code_owners.md) to specify the actual owners and granular permissions. -Using Code Owners in conjunction with [protected branches](protected_branches.md#protected-branches-approval-by-code-owners) +Using Code Owners in conjunction with [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch) prevents any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as @@ -107,20 +107,7 @@ Code Owners is required. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules, Code Owners included. -## The syntax of Code Owners files - -Files can be specified using the same kind of patterns you would use -in the `.gitignore` file followed by one or more of: - -- A user's `@username`. -- A user's email address. -- The `@name` of one or more groups that should be owners of the file. -- Lines starting with `#` are ignored. - -The path definition order is significant: the last pattern -matching a given path is used to find the code owners. - -### Groups as Code Owners +## Groups as Code Owners > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. > - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 89c82d4dc6f..a09448d4755 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -59,7 +59,7 @@ specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the environments list, verify that what's running in staging is what you think is - running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production. + running, then click on the [manual action](../../ci/yaml/index.md#whenmanual) to deploy to production. - You trigger a deploy, and you have many containers to upgrade so you know this takes a while (you've also throttled your deploy to only take down X containers at a time). But you need to tell someone when it's deployed, so you @@ -88,7 +88,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). -1. [Configure GitLab Runner](../../ci/runners/README.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +1. [Configure GitLab Runner](../../ci/runners/index.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you need it @@ -165,6 +165,6 @@ version of your application. ## Further reading - [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy) -- [GitLab CI/CD variables](../../ci/variables/README.md) +- [GitLab CI/CD variables](../../ci/variables/index.md) - [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index c0bc97781b6..1b9a17ee071 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -28,7 +28,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is enabled on your repository. A good rule to follow is to provide access only to trusted users, -and make sure that the allowed users have the [Maintainer role or higher](../../permissions.md) +and make sure that the allowed users have at least the [Maintainer role](../../permissions.md) in the GitLab project. If this security implication is a concern for your organization, @@ -121,8 +121,9 @@ repositories to secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: -1. Go to **Admin Area > Deploy Keys**. -1. Click on **New deploy key**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Deploy Keys**. +1. Select **New deploy key**. Make sure your new key has a meaningful title, as it is the primary way for project maintainers and owners to identify the correct public deploy key to add. For example, diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 711d7f561e4..72ef88b5fab 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Description templates +# Description templates **(FREE)** We all know that a properly submitted issue is more likely to be addressed in a timely manner by the developers of a project. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index eb963cb74c5..5ffde38b348 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -34,7 +34,7 @@ GitLab supports two different modes of file locking: ## Permissions Locks can be created by any person who has at least -[Developer permissions](../permissions.md) to the repository. +[Developer role](../permissions.md) in the repository. Only the user who locked the file or directory can edit locked files. Other users are prevented from modifying locked files by pushing, merging, diff --git a/doc/user/project/img/protected_branches_delete.png b/doc/user/project/img/protected_branches_delete.png Binary files differdeleted file mode 100644 index 8910ae9e39d..00000000000 --- a/doc/user/project/img/protected_branches_delete.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png Binary files differdeleted file mode 100644 index ccd23dbe160..00000000000 --- a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_matches.png b/doc/user/project/img/protected_branches_matches.png Binary files differdeleted file mode 100644 index d7f2c8582fc..00000000000 --- a/doc/user/project/img/protected_branches_matches.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_select_roles_and_users.png b/doc/user/project/img/protected_branches_select_roles_and_users.png Binary files differdeleted file mode 100644 index 4f62b057cc7..00000000000 --- a/doc/user/project/img/protected_branches_select_roles_and_users.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_select_roles_and_users_list.png b/doc/user/project/img/protected_branches_select_roles_and_users_list.png Binary files differdeleted file mode 100644 index 519f2267496..00000000000 --- a/doc/user/project/img/protected_branches_select_roles_and_users_list.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 963b9f524ff..7ccdb632c19 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -36,7 +36,7 @@ created as private in GitLab as well. - Attachments in Markdown are not imported. - Task lists are not imported. - Emoji reactions are not imported. -- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are +- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are supported). ## How it works @@ -51,7 +51,7 @@ The Bitbucket Server importer works as follows: ### User assignment When issues/pull requests are being imported, the Bitbucket importer tries to -find the author's e-mail address with a confirmed e-mail address in the GitLab +find the author's email address with a confirmed email address in the GitLab user database. If no such user is available, the project creator is set as the author. The importer appends a note in the comment to mark the original creator. diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index d3d77f16200..982bc6d90e8 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -7,31 +7,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab **(FREE)** -It only takes a few simple steps to import your project from FogBugz. -The importer imports all your cases and comments with original case -numbers and timestamps. You can also map FogBugz users to GitLab users. +Using the importer, you can import your FogBugz project to GitLab.com +or to your self-managed GitLab instance. -Follow these steps to import your project from FogBugz: +The importer imports all of your cases and comments with the original +case numbers and timestamps. You can also map FogBugz users to GitLab +users. -1. From your GitLab dashboard, select **New project**. +To import your project from FogBugz: +1. From your GitLab dashboard, select **New project**. 1. Select the **FogBugz** button. - -  - +  1. Enter your FogBugz URL, email address, and password. - -  - -1. Create mapping from FogBugz users to GitLab users. - -  - -1. Select the projects you wish to import by selecting the **Import** buttons. - -  - -1. Once the import finishes, click the link to go to the project +  +1. Create a mapping from FogBugz users to GitLab users. +  +1. Select **Import** for the projects you want to import. +  +1. After the import finishes, click the link to go to the project dashboard. Follow the directions to push your existing repository. - -  +  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 99b3e1acdcf..e67b6a45280 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -28,7 +28,7 @@ The following aspects of a project are imported: References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility -level is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), +level is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `gitlab.com/customer-success`. You can do some bulk actions to move projects to different namespaces in the rails console. @@ -60,7 +60,7 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) that matches their GitLab account's email address. NOTE: @@ -134,6 +134,9 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. Once done, you'll be taken to the importer page to select the repositories to import. +To use a newer personal access token in imports after previously performing these steps, sign out of +your GitLab account and sign in again, or revoke the older personal access token in GitHub. + ### Select which repositories to import After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and @@ -160,6 +163,9 @@ Additionally, you can configure GitLab to send pipeline status updates back GitH If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both of the above are automatically configured. **(PREMIUM)** +NOTE: +Mirroring does not sync any new or updated pull requests from your GitHub project. + ## Improve the speed of imports on self-managed instances NOTE: diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 05fd04f6e48..dcc41c6c85e 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -49,7 +49,7 @@ When migrating to GitLab.com, you must create users manually unless [SCIM](../.. will be used. Creating users with the API is limited to self-managed instances as it requires administrator access. -To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/README.md). +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). Migrate the assets in this order: 1. [Groups](../../../api/groups.md) @@ -74,6 +74,10 @@ best to [back up](../../../raketasks/backup_restore.md) the existing instance and restore it on the new instance. For example, this is useful when migrating a self-managed instance from an old server to a new server. +The backups produced don't depend on the operating system running GitLab. You can therefore use +the restore method to switch between different operating system distributions or versions, as long +as the same GitLab version [is available for installation](https://docs.gitlab.com/omnibus/package-information/deprecated_os.md). + To instead merge two self-managed GitLab instances together, use the instructions in [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). This method is useful when both self-managed instances have existing data that must be preserved. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 4273f90c1e7..07419080d7d 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your Jira project issues to GitLab +# Import your Jira project issues to GitLab **(PREMIUM)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 0dcbf997452..fca9c3e7023 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -65,7 +65,7 @@ Projects include the following [features](https://about.gitlab.com/features/): **GitLab CI/CD:** -- [GitLab CI/CD](../../ci/README.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. +- [GitLab CI/CD](../../ci/index.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. - [Container Registry](../packages/container_registry/index.md): Build and push Docker images. - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD @@ -134,7 +134,7 @@ To review or contribute to the extension's code, visit [its codebase in GitLab]( ## Project APIs -There are numerous [APIs](../../api/README.md) to use with your projects: +There are numerous [APIs](../../api/index.md) to use with your projects: - [Badges](../../api/project_badges.md) - [Clusters](../../api/project_clusters.md) diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 4f5640d9fff..019ca9da9f1 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -18,7 +18,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ## Configuration -This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo:status` access granted. Complete these steps on GitHub: diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 0668e5dd88f..d5dc02d5455 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -36,7 +36,7 @@ Select a room and create a webhook: 1. Select **Save**. 1. Copy the webhook URL. -For further details, see [the Google Chat documentation for configuring webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks). +For further details, see [the Google Chat documentation for configuring webhooks](https://developers.google.com/chat/how-tos/webhooks). ## In GitLab diff --git a/doc/user/project/integrations/img/project_integrations_v13_3.png b/doc/user/project/integrations/img/project_integrations_v13_3.png Binary files differdeleted file mode 100644 index 9c925d32441..00000000000 --- a/doc/user/project/integrations/img/project_integrations_v13_3.png +++ /dev/null diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md deleted file mode 100644 index c9ab4532760..00000000000 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../../integration/jira/jira_cloud_configuration.md' -remove_date: '2021-06-18' ---- - -This document was moved to [another location](../../../integration/jira/jira_cloud_configuration.md). - -<!-- This redirect file can be deleted after <2021-06-18>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md deleted file mode 100644 index de6eec62b96..00000000000 --- a/doc/user/project/integrations/jira_server_configuration.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../../integration/jira/jira_server_configuration.md' -remove_date: '2021-06-18' ---- - -This document was moved to [another location](../../../integration/jira/jira_server_configuration.md). - -<!-- This redirect file can be deleted after <2021-06-18>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 834bf15c287..619ae52481b 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -141,7 +141,7 @@ The available slash commands for Mattermost are: | ------- | ----------- | ------- | | <kbd>/<trigger> issue new <title> <kbd>⇧ Shift</kbd>+<kbd>↵ Enter</kbd> <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | | <kbd>/<trigger> issue show <issue-number></kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | -| <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/README.md). | `/gitlab deploy staging to production` | +| <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | To see a list of available commands to interact with GitLab, type the trigger word followed by <kbd>help</kbd>. Example: `/gitlab help` diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index b0ae290e7cd..53aa9da30ab 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -15,11 +15,9 @@ functionality to GitLab. You can find the available integrations under your project's **Settings > Integrations** page. -There are more than 20 integrations to integrate with. Click on the one that you +There are more than 20 integrations to integrate with. Select the one that you want to configure. - - ## Integrations listing Click on the service links to see further configuration instructions and details. @@ -34,6 +32,7 @@ Click on the service links to see further configuration instructions and details | Campfire | Connect to chat. | **{dotted-circle}** No | | [Confluence Workspace](../../../api/services.md#confluence-service) | Replace the link to the internal wiki with a link to a Confluence Cloud Workspace. | **{dotted-circle}** No | | [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | +| [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | **{check-circle}** Yes | | [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | **{dotted-circle}** No | | Drone CI | Run CI/CD pipelines with Drone. | **{check-circle}** Yes | | [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | @@ -51,7 +50,7 @@ Click on the service links to see further configuration instructions and details | [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | | Packagist | Update your projects. | **{check-circle}** Yes | | Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | -| PivotalTracker | Use PivotalTracker as the issue tracker. | **{dotted-circle}** No | +| [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | @@ -115,6 +114,6 @@ plugins. This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. For an overview of what integrations are available, please see the -[project_services source directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/models/project_services). +[integrations source directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/models/integrations). Contributions are welcome! diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md new file mode 100644 index 00000000000..c2c827c240b --- /dev/null +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -0,0 +1,47 @@ +--- +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Pivotal Tracker service **(FREE)** + +This service adds commit messages as comments to Pivotal Tracker stories. + +Once enabled, commit messages are checked for square brackets containing a hash mark followed by +the story ID (for example, `[#555]`). Every story ID found gets the commit comment added to it. + +You can also close a story with a message containing: `fix [#555]`. +You can use any of these words: + +- `fix` +- `fixed` +- `fixes` +- `complete` +- `completes` +- `completed` +- `finish` +- `finished` +- `finishes` +- `delivers` + +Read more about the +[Source Commits endpoint](https://www.pivotaltracker.com/help/api/rest/v5#Source_Commits) in +the Pivotal Tracker API documentation. + +See also the [Pivotal Tracker service API documentation](../../../api/services.md#pivotal-tracker). + +## Set up Pivotal Tracker + +In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/articles/api_token/). + +Complete these steps in GitLab: + +1. Go to the project you want to configure. +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Pivotal Tracker**. +1. Ensure that the **Active** toggle is enabled. +1. Paste the token you generated in Pivotal Tracker. +1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** + field, separated with commas. +1. Select **Save changes** or optionally select **Test settings**. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 584c0898fec..fe74ea6834b 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -35,6 +35,6 @@ In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the -[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-cicd-variables), +[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/index.md#predefined-cicd-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#exporters). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 1bafa4938af..ea0119f2e94 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -40,7 +40,7 @@ Prometheus needs to be deployed into the cluster and configured properly in orde In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. -Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. +Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/index.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. ## Displaying Canary metrics **(PREMIUM)** diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 05515c58161..2851fe0b299 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -13,7 +13,7 @@ You can configure GitLab to send notifications to a Webex Teams space: ## Create a webhook for the space -1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/messaging/applications/incoming-webhooks-cisco-systems-38054). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054). 1. Select **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space to receive the notifications. 1. Select **ADD**. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 406b1e9ba6b..01f3424d993 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -112,7 +112,7 @@ branches, this hook isn't executed. X-Gitlab-Event: Push Hook ``` -**Request body:** +**Payload example:** ```json { @@ -202,7 +202,7 @@ tags, this hook is not executed. X-Gitlab-Event: Tag Push Hook ``` -**Request body:** +**Payload example:** ```json { @@ -256,7 +256,14 @@ Triggered when a new issue is created or an existing issue was updated/closed/re X-Gitlab-Event: Issue Hook ``` -**Request body:** +**Available `object_attributes.action`:** + +- `open` +- `close` +- `reopen` +- `update` + +**Payload example:** ```json { @@ -423,7 +430,7 @@ Valid target types: X-Gitlab-Event: Note Hook ``` -**Request body:** +**Payload example:** ```json { @@ -505,7 +512,7 @@ X-Gitlab-Event: Note Hook X-Gitlab-Event: Note Hook ``` -**Request body:** +**Payload example:** ```json { @@ -634,7 +641,7 @@ X-Gitlab-Event: Note Hook X-Gitlab-Event: Note Hook ``` -**Request body:** +**Payload example:** ```json { @@ -742,7 +749,7 @@ NOTE: X-Gitlab-Event: Note Hook ``` -**Request body:** +**Payload example:** ```json { @@ -820,7 +827,17 @@ Triggered when a new merge request is created, an existing merge request was upd X-Gitlab-Event: Merge Request Hook ``` -**Request body:** +**Available `object_attributes.action`:** + +- `open` +- `close` +- `reopen` +- `update` +- `approved` +- `unapproved` +- `merge` + +**Payload example:** ```json { @@ -983,7 +1000,7 @@ Triggered when a wiki page is created, updated or deleted. X-Gitlab-Event: Wiki Page Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1044,7 +1061,7 @@ Triggered on status change of Pipeline. X-Gitlab-Event: Pipeline Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1291,7 +1308,7 @@ Triggered on status change of a job. X-Gitlab-Event: Job Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1340,7 +1357,7 @@ X-Gitlab-Event: Job Hook }, "runner": { "active": true, - "runner_type": "project_type", + "runner_type": "project_type", "is_shared": false, "id": 380987, "description": "shared-runners-manager-6.gitlab.com", @@ -1370,7 +1387,7 @@ Triggered when a deployment: X-Gitlab-Event: Deployment Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1433,7 +1450,7 @@ Member events are triggered when: X-Gitlab-Event: Member Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1461,7 +1478,7 @@ X-Gitlab-Event: Member Hook X-Gitlab-Event: Member Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1489,7 +1506,7 @@ X-Gitlab-Event: Member Hook X-Gitlab-Event: Member Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1526,7 +1543,7 @@ Subgroup events are triggered when: X-Gitlab-Event: Subgroup Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1554,7 +1571,7 @@ X-Gitlab-Event: Subgroup Hook X-Gitlab-Event: Subgroup Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1587,7 +1604,7 @@ Triggered when a feature flag is turned on or off. X-Gitlab-Event: Feature Flag Hook ``` -**Request Body**: +**Payload example**: ```json { @@ -1637,7 +1654,12 @@ Triggered when a release is created or updated. X-Gitlab-Event: Release Hook ``` -**Request Body**: +**Available `object_attributes.action`:** + +- `create` +- `update` + +**Payload example**: ```json { @@ -1762,6 +1784,10 @@ On this page, you can see data that GitLab sends (request headers and body) and From this page, you can repeat delivery with the same data by clicking `Resend Request` button. NOTE: +This history is unavailable for Group-level webhooks. For more information, read +[issue #325642](https://gitlab.com/gitlab-org/gitlab/-/issues/325642). + +NOTE: If URL or secret token of the webhook were updated, data is delivered to the new address. ### Webhook fails or multiple webhook requests are triggered diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 8f71d469e34..a32a8ed8ec7 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -97,8 +97,8 @@ For examples of using issue boards along with [epics](../group/epics/index.md), ### Use cases for a single issue board -With the GitLab Workflow you can discuss proposals in issues, label -them, and organize and prioritize them with issue boards. +With the [GitLab Flow](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/) you can +discuss proposals in issues, label them, and organize and prioritize them with issue boards. For example, let's consider this simplified development workflow: @@ -154,7 +154,7 @@ for them. NOTE: For a broader use case, please see the blog post -[GitLab Workflow, an Overview](https://about.gitlab.com/topics/version-control/what-is-gitlab-workflow/#gitlab-workflow-a-use-case-scenario). +[What is GitLab Flow?](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/). For a real use case example, you can read why [Codepen decided to adopt issue boards](https://about.gitlab.com/blog/2017/01/27/codepen-welcome-to-gitlab/#project-management-everything-in-one-place) to improve their workflow with multiple boards. @@ -426,7 +426,7 @@ To set a WIP limit for a list: 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. -## Blocked issues +## Blocked issues **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. > - [View blocking issues when hovering over blocked icon](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10. diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index f98e94c66ae..e020bdee737 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Associate a Zoom meeting with an issue +# Associate a Zoom meeting with an issue **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index ed15d7a2e63..92c26fb654e 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -4,11 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Confidential issues +# Confidential issues **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3282) in GitLab 8.6. - -Confidential issues are issues visible only to members of a project with +Confidential issues are [issues](index.md) visible only to members of a project with [sufficient permissions](#permissions-and-access-to-confidential-issues). Confidential issues can be used by open source projects and companies alike to keep security vulnerabilities private or prevent surprises from leaking out. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 63b38520c98..2b07131df6e 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -4,9 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Crosslinking issues +# Crosslinking issues **(FREE)** -There are several ways to mention an issue or make issues appear in each other's +There are several ways to mention an issue or make [issues](index.md) appear in each other's [Linked issues](related_issues.md) section. For more information on GitLab Issues, read the [issues documentation](index.md). diff --git a/doc/user/project/issues/img/issue_type_change_v13_12.png b/doc/user/project/issues/img/issue_type_change_v13_12.png Binary files differindex 3b4864ffbbb..55aa607b878 100644 --- a/doc/user/project/issues/img/issue_type_change_v13_12.png +++ b/doc/user/project/issues/img/issue_type_change_v13_12.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 13f5beadb16..2ef12cd1240 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Data and Actions +# Issue Data and Actions **(FREE)** Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. @@ -151,7 +151,7 @@ cannot access the issue, and it is not listed in the project's issue boards nor ### Lock issue -You can [lock the threads](../../discussions/index.md#lock-discussions) in the issue, +You can [lock the issue](../../discussions/index.md#prevent-comments-by-locking-an-issue) to prevent further comments from being added. ### Participants @@ -288,7 +288,7 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). After you write a comment, you can: - Click **Comment** to publish your comment. -- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) +- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#create-a-thread-without-replying-to-a-comment) in that issue's main thread to discuss specific points. This invites other participants to reply directly to your thread, keeping related comments grouped together. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 35573518626..c570bc9612a 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Managing issues +# Managing issues **(FREE)** [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and planning work in GitLab. @@ -333,7 +333,7 @@ of your installation. ## Change the issue type -Users with [developer permission](../../permissions.md) +Users with the [Developer role](../../permissions.md) can change an issue's type. To do this, edit the issue and select an issue type from the **Issue type** selector menu: diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 97a790c2527..2681a39aeb6 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can sort a list of issues several ways, including by: -- Blocking +- Blocking **(PREMIUM)** - Created date - Due date - Label priority @@ -51,7 +51,7 @@ This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-is Changing the order in an issue list changes the ordering in an issue board, and vice versa. -## Sorting by blocking issues +## Sorting by blocking issues **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index e7adc045e98..43d6ab2070d 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -59,7 +59,7 @@ and edit labels. > Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. -To view a project's available labels, in the project, go to **Issues > Labels**. +To view a project's available labels, in the project, go to **Project information > Labels**. Its list of labels includes both the labels defined at the project level, and all labels defined by its ancestor groups. For each label, you can see the project or group path from where it was created. You can filter the list by @@ -68,7 +68,7 @@ icon (**{search}**). To create a new project label: -1. In your project, go to **Issues > Labels**. +1. In your project, go to **Project information > Labels**. 1. Select the **New label** button. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). @@ -118,18 +118,18 @@ Promoting a label is a permanent action, and cannot be reversed. To promote a project label to a group label: -1. Navigate to **Issues > Labels** in the project. +1. Navigate to **Project information > Labels** in the project. 1. Click on the three dots (**{ellipsis_v}**) next to the **Subscribe** button and select **Promote to group label**. ### Group labels -To view the group labels list, navigate to the group and click **Issues > Labels**. +To view the group labels list, navigate to the group and click **Group information > Labels**. The list includes all labels that are defined at the group level only. It does not list any labels that are defined in projects. You can filter the list by entering a search query at the top and clicking search (**{search}**). -To create a **group label**, navigate to **Issues > Labels** in the group and +To create a **group label**, navigate to **Group information > Labels** in the group and follow the same process as [creating a project label](#project-labels). #### Create group labels from epics **(ULTIMATE)** diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 11d6bfb5d0c..8987c663860 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -24,7 +24,7 @@ To add a user to a project: 1. Go to your project and select **Project information > Members**. 1. On the **Invite member** tab, under **GitLab member or Email address**, type the username or email address. In GitLab 13.11 and later, you can [replace this form with a modal window](#add-a-member-modal-window). -1. Select a [role](../../permissions.md). +1. Select a [role](../../permissions.md). 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. 1. Select **Invite**. @@ -54,7 +54,7 @@ To add groups to a project: 1. Go to your project and select **Project information > Members**. 1. On the **Invite group** tab, under **Select a group to invite**, choose a group. -1. Select the highest max [role](../../permissions.md) for users in the group. +1. Select the highest max [role](../../permissions.md) for users in the group. 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. 1. Select **Invite**. @@ -99,6 +99,8 @@ In this example: - **Administrator** is the [Owner](../../permissions.md) and member of all groups. They have inherited their role from the **demo** group. +If a user is a direct member of a project, the expiration date can be updated. If membership is inherited from a parent group, the expiration date can be updated only from the parent group itself. + ## Remove a member from a project If a user is a direct member of a project, you can remove them. @@ -156,7 +158,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last ## Request access to a project -GitLab users can request to become a member of a project. +GitLab users can request to become a member of a project. 1. Go to the project you'd like to be a member of. 1. By the project name, select **Request Access**. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 76aff18b00d..2bc6d5bb148 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. If your application offers a web interface and you are using -[GitLab CI/CD](../../../ci/README.md), you can quickly determine the accessibility +[GitLab CI/CD](../../../ci/index.md), you can quickly determine the accessibility impact of pending code changes. ## Overview @@ -37,7 +37,7 @@ This example shows how to run [pa11y](https://pa11y.org/) on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). For GitLab 12.9 and later, to define the `a11y` job, you must -[include](../../../ci/yaml/README.md#includetemplate) the +[include](../../../ci/yaml/index.md#includetemplate) the [`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) included with your GitLab installation, as shown below. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 3c47c2af344..40345f33cb2 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -11,11 +11,21 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge > Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. You can configure your merge requests so that they must be approved before -they can be merged. You can do this by creating [rules](rules.md) or by specifying -a list of users who act as [code owners](../../code_owners.md) for specific files. - -You can configure merge request approvals for each project. In higher GitLab tiers, -Administrators of self-managed GitLab instances can configure approvals +they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows +all users with Developer or greater [permissions](../../../permissions.md) to +approve merge requests, these approvals are [optional](#optional-approvals). +[GitLab Premium](https://about.gitlab.com/pricing/) and +[GitLab Ultimate](https://about.gitlab.com/pricing/) provide additional +flexibility: + +- Create required [rules](rules.md) about the number and type of approvers before work can merge. +- Specify a list of users who act as [code owners](../../code_owners.md) for specific files, + and require their approval before work can merge. + +You can configure merge request approvals on a per-project basis. Administrators of +[GitLab Premium](https://about.gitlab.com/pricing/) and +[GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances +can also configure approvals [for the entire instance](../../../admin_area/merge_requests_approvals.md). ## How approvals work @@ -60,7 +70,7 @@ a merge request. After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, -such as merge conflicts, [pending discussions](../../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), +such as merge conflicts, [pending discussions](../../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved), or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). To prevent merge request authors from approving their own merge requests, @@ -94,6 +104,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple database, for all proposed code changes. - Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), to determine who should review the work. +- Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 1e4b0f659ee..82685f9101e 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval rules **(FREE)** +# Merge request approval rules **(PREMIUM)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. You can define approval rules: @@ -159,7 +159,7 @@ become eligible approvers in the project. To enable this merge request approval  You can also -[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) +[require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) for protected branches. **(PREMIUM)** ## Merge request approval segregation of duties **(PREMIUM)** @@ -173,6 +173,7 @@ Some users (like managers) may not need permission to push or merge code, but st oversight on proposed work. To enable approval permissions for these users without granting them push access: +1. [Create a protected branch](../../protected_branches.md) 1. [Create a new group](../../../group/index.md#create-a-group). 1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. @@ -180,7 +181,7 @@ granting them push access: based on the Reporter role. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select **Add approval rule** or **Update approval rule**. +1. Select **Add approval rule** or **Update approval rule** and target the protected branch. 1. [Add the group](../../../group/index.md#create-a-group) to the permission list.  @@ -203,7 +204,7 @@ on a merge request, you can either add or remove approvers: Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) to prevent users from overriding approval rules for merge requests. -## Configure optional approval rules +## Configure optional approval rules **(PREMIUM)** Merge request approvals can be optional for projects where approvals are appreciated, but not required. To make an approval rule optional: @@ -229,4 +230,4 @@ approval rule for certain branches:  1. To enable this configuration, read - [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). + [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index b72a4125d0e..8a81ff8c94b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -115,8 +115,16 @@ permission enables an electronic signature for approvals, such as the one define ## Security approvals in merge requests **(ULTIMATE)** You can require that a member of your security team approves a merge request if a -merge request could introduce a vulnerability. To learn more, see -[Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). +merge request could introduce a vulnerability. + +To learn more, see [Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). + +## Code coverage check approvals **(PREMIUM)** + +You can require specific approvals if a merge request would result in a decline in code test +coverage. + +To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). ## Related links diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 930df65f3fc..339f67f828f 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -17,7 +17,7 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers -get Developer access. +get the Developer role. Maintainers mark the authoritative branches as 'Protected'. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index d11ad53a9d6..eff3a5bd99e 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. If your application offers a web interface and you're using -[GitLab CI/CD](../../../ci/README.md), you can quickly determine the rendering performance +[GitLab CI/CD](../../../ci/index.md), you can quickly determine the rendering performance impact of pending code changes in the browser. NOTE: @@ -40,7 +40,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance). +[Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -89,7 +89,7 @@ The above example: GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 27642a9bd5d..19302572dc9 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -10,17 +10,22 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. -Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your -source code quality using GitLab Code Quality. +To ensure your project's code stays simple, readable, and easy to contribute to, +you can use [GitLab CI/CD](../../../ci/index.md) to analyze your source code quality. + +For example, while you're implementing a feature, you can run Code Quality reports +to analyze how your improvements are impacting your code's quality. You can +use this information to ensure that your changes are improving performance rather +than degrading it. Code Quality: -- Uses [Engines](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are +- Uses [plugins](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are free and open source. Code Quality does not require a Code Climate subscription. -- Runs in [pipelines](../../../ci/pipelines/index.md) using a Docker image built in the - [GitLab Code - Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). +- Runs in [pipelines](../../../ci/pipelines/index.md) by using a Docker image built in the + [GitLab Code Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project. +- Uses [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). - Is available by using [Auto Code Quality](../../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../../topics/autodevops/index.md). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). @@ -54,42 +59,14 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. -> - [Feature enhanced](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. +> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.1. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example:  -Previously, an indicator was displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view: - - - -To switch to the previous version of this feature, a GitLab administrator can run the following in a -[Rails console](../../../administration/operations/rails_console.md): - -```ruby -# For the instance -Feature.disable(:codequality_mr_diff_annotations) -# For a single project -Feature.disable(:codequality_mr_diff_annotations, Project.find(<project id>)) -``` - -## Use cases - -For instance, consider the following workflow: - -1. Your backend team member starts a new implementation for making a certain - feature in your app faster. -1. With Code Quality reports, they analyze how their implementation is impacting - the code quality. -1. The metrics show that their code degrades the quality by 10 points. -1. You ask a co-worker to help them with this modification. -1. They both work on the changes until Code Quality report displays no - degradations, only improvements. -1. You approve the merge request and authorize its deployment to staging. -1. Once verified, their changes are deployed to production. - ## Example configuration This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. @@ -111,7 +88,7 @@ include: The above example creates a `code_quality` job in your CI/CD pipeline which scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -262,13 +239,13 @@ was chosen as an operational decision by the runner team, instead of exposing `d ### Disabling the code quality job The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable -is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/README.md) +is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/index.md) to learn more about how to define one. To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. This can be done: -- For [the whole project](../../../ci/variables/README.md#custom-cicd-variables). +- For [the whole project](../../../ci/variables/index.md#custom-cicd-variables). - For a single pipeline run: 1. Go to **CI/CD > Pipelines** @@ -278,11 +255,11 @@ This can be done: ### Using with merge request pipelines The configuration provided by the Code Quality template does not let the `code_quality` job -run on [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md). +run on [pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md). If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined. -The template has these [`rules`](../../../ci/yaml/README.md#rules) for the `code quality` job: +The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code quality` job: ```yaml code_quality: @@ -292,7 +269,7 @@ code_quality: - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' ``` -If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow)) +If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/index.md#workflow)) might look like this example: ```yaml @@ -334,7 +311,7 @@ do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the [Code Quality report - artifact](../../../ci/yaml/README.md#artifactsreportscodequality). + artifact](../../../ci/yaml/index.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). @@ -342,13 +319,13 @@ do this: The Code Quality report artifact JSON file must contain an array of objects with the following properties: -| Name | Description | -| ---------------------- | -------------------------------------------------------------------------------------- | -| `description` | A description of the code quality violation. | -| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | -| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | -| `location.path` | The relative path to the file containing the code quality violation. | -| `location.lines.begin` | The line on which the code quality violation occurred. | +| Name | Description | +| ---------------------- | ----------------------------------------------------------------------------------------- | +| `description` | A description of the code quality violation. | +| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | +| `location.path` | The relative path to the file containing the code quality violation. | +| `location.lines.begin` or `location.positions.begin.line` | The line on which the code quality violation occurred. | Example: @@ -371,6 +348,8 @@ Example: NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. +The GitLab parser does not allow a [byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark) +at the beginning of the file. ## Code Quality reports **(PREMIUM)** @@ -389,7 +368,7 @@ After the Code Quality job completes: - The full list of code quality violations generated by a pipeline is shown in the Code Quality tab of the Pipeline Details page. **(PREMIUM)** -### Generating an HTML report +## Generate an HTML report In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), it is possible to generate an HTML report file by setting the `REPORT_FORMAT` @@ -535,7 +514,7 @@ This can be due to multiple reasons: - Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. -- The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD +- The [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 1bda12468a3..fb1b7f8b9b6 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -26,3 +26,62 @@ To seamlessly navigate among commits in a merge request: - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  + +## View merge request commits in context + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12. +> - [Deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-viewing-merge-request-commits-in-context). **(FREE SELF)** + +WARNING: +This feature is in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +and is [incomplete](https://gitlab.com/groups/gitlab-org/-/epics/1192). +Previously merged commits can be added, but they can't be removed due to +[this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538). + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +When reviewing a merge request, it helps to have more context about the changes +made. That includes unchanged lines in unchanged files, and previous commits +that have already merged that the change is built on. + +To add previously merged commits to a merge request for more context: + +1. Go to your merge request. +1. Select the **Commits** tab. +1. Scroll to the end of the list of commits, and select **Add previously merged commits**: + +  + +1. Select the commits that you want to add. +1. Select **Save changes**. + +To view the changes done on those previously merged commits: + +1. On your merge request, select the **Changes** tab. +1. Scroll to **(file-tree)** **Compare** and select **previously merged commits**: + +  + +### Enable or disable viewing merge request commits in context **(FREE SELF)** + +Viewing merge request commits in context is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:context_commits) +``` + +To disable it: + +```ruby +Feature.disable(:context_commits) +``` diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 430c6488b26..0d56fbc89b8 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,189 +7,155 @@ description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# How to create a merge request **(FREE)** +# Creating merge requests **(FREE)** -Before creating a merge request, read through an -[introduction to merge requests](getting_started.md) -to familiarize yourself with the concept, the terminology, -and to learn what you can do with them. +There are many different ways to create a merge request. -Every merge request starts by creating a branch. You can either -do it locally through the [command line](#new-merge-request-from-your-local-environment), via a Git CLI application, -or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through-the-ui). +## From the merge request list -This document describes the several ways to create a merge request. +You can create a merge request from the list of merge requests. -When you start a new merge request, regardless of the method, -you are taken to the [**New merge request** page](#new-merge-request-page) -to fill it with information about the merge request. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Merge requests**. +1. In the top right, select **New merge request**. +1. Select a source and target branch and then **Compare branches and continue**. +1. Fill out the fields and select **Create merge request**. -If you push a new branch to GitLab, also regardless of the method, -you can click the [**Create merge request**](#create-merge-request-button) -button and start a merge request from there. +## From an issue -## New merge request page +You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). -On the **New merge request** page, start by filling in the title and description -for the merge request. If commits already exist on the branch, GitLab suggests a -merge request title for you: +## When you add, edit, or upload a file -- **If a multi-line commit message exists**: GitLab adds the first line of the - first multi-line commit message as the title. Any additional lines in that - commit message become the description. -- **If no multi-line commit message exists**: GitLab adds the branch name as the - title, and leaves the description blank. +You can create a merge request when you add, edit, or upload a file to a repository. -The title is the only field that is mandatory in all cases. +1. Add, edit, or upload a file to the repository. +1. In the **Commit message**, enter a reason for the commit. +1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). +1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only + if the target is not the same as the source branch, or if the source branch is protected. +1. Select **Commit changes**. -From there, you can fill it with information (title, description, -assignee(s), milestone, labels, approvers) and click **Create merge request**. +## When you create a branch -From that initial screen, you can also see all the commits, -pipelines, and file changes pushed to your branch before submitting -the merge request. +You can create a merge request when you create a branch. - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Repository > Branches**. +1. Type a branch name and select **New branch**. +1. Above the file list, on the right side, select **Create merge request**. + A merge request is created. The default branch is the target. +1. Fill out the fields and select **Create merge request**. -NOTE: -You can push one or more times to your branch in GitLab before -creating the merge request. +## When you use Git commands locally -## Create merge request button +You can create a merge request by running Git commands on your local machine. -Once you have pushed a new branch to GitLab, visit your repository -in GitLab and to see a call-to-action at the top of your screen -from which you can click the button **Create merge request**. +1. Create a branch: - + ```shell + git checkout -b my-new-branch + ``` -You can also see the **Create merge request** button in the top-right of the: +1. Create, edit, or delete files. The stage and commit them: -- **Project** page. -- **Repository > Files** page. -- **Merge requests** page. + ```shell + git add . + git commit -m "My commit message" + ``` -In this case, GitLab uses the most recent branch you pushed -changes to as the source branch, and the default branch in the current -project as the target. +1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): -## New merge request by adding, editing, and uploading a file + ```shell + git push origin my-new-branch + ``` -When you choose to edit, add, or upload a file through the GitLab UI, -at the end of the file you see the option to add the **Commit message**, -to select the **Target branch** of that commit, and the checkbox to -**Start new a merge request with these changes**. + GitLab prompts you with a direct link for creating a merge request: -Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options. + ```plaintext + ... + remote: To create a merge request for docs-new-merge-request, visit: + remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch + ``` -Once you have added, edited, or uploaded the file: +1. Copy the link and paste it in your browser. -1. Describe your changes in the commit message. -1. Select an existing branch to add your commit into, or, if you'd like to create a new branch, type the new branch name (without spaces, capital letters, or special chars). -1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request. -1. Click **Commit changes**. +You can add other [flags to commands when pushing through the command line](../push_options.md) +to reduce the need for editing merge requests manually through the UI. -If you chose to start a merge request, you are taken to the -[**New merge request** page](#new-merge-request-page), from -which you can fill it in with information and submit the merge request. +## When you work in a fork -The merge request targets the default branch of the repository. -If you want to change it, you can do it later by editing the merge request. +You can create a merge request from your fork to contribute back to the main project. -## New merge request from a new branch created through the UI - -To quickly start working on files through the GitLab UI, -navigate to your project's **Repository > Branches** and click -**New branch**. A new branch is created and you can start -editing files. - -Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button) -button to open the [**New merge request** page](#new-merge-request-page). -A new merge request is started using the current branch as the source, -and the default branch in the current project as the target. - -## New merge request from your local environment - -Assuming you have your repository cloned into your computer and you'd -like to start working on changes to files, start by creating and -checking out a new branch: - -```shell -git checkout -b my-new-branch -``` - -Work on your file changes, stage, and commit them: +1. On the top bar, select **Menu > Project**. +1. Select your fork of the repository. +1. On the left menu, go to **Merge requests**, and select **New merge request**. +1. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch. +1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. + You can set a [default target project](#set-the-default-target-project) to + change the default target branch (which can be useful if you are working in a + forked project). +1. Select **Compare branches and continue**. +1. Select **Submit merge request**. -```shell -git add . -git commit -m "My commit message" -``` +After your work is merged, if you don't intend to +make any other contributions to the upstream project, you can unlink your +fork from its upstream project. Go to **Settings > Advanced Settings** and +[remove the forking relationship](../settings/index.md#removing-a-fork-relationship). -Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): +For more information, [see the forking workflow documentation](../repository/forking_workflow.md). -```shell -git push origin my-new-branch -``` +## By sending an email **(FREE SELF)** -In the output, GitLab prompts you with a direct link for creating -a merge request: +> The format of the generated email address changed in GitLab 11.7. + The earlier format is still supported so existing aliases + or contacts still work. -```shell -... -remote: To create a merge request for docs-new-merge-request, visit: -remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch -``` +You can create a merge request by sending an email message to GitLab. +The merge request target branch is the project's default branch. -Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page) -is displayed. +Prerequisites: -There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. +- A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md). +- A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md). -If you didn't push your branch to GitLab through the command line -(for example, you used a Git CLI application to push your changes), -you can create a merge request through the GitLab UI by clicking -the [**Create merge request**](#create-merge-request-button) button. +To create a merge request by sending an email: -## New merge request from an issue +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Merge requests**. +1. In the top right, select **Email a new merge request to this project**. + An email address is displayed. Copy this address. + Ensure you keep this address private. +1. Open an email and compose a message with the following information: -You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). + - The **To** line is the email address you copied. + - The subject line is the source branch name. + - The message body is the merge request description. -## New merge request from the merge requests page +1. Send the email message. -You can start creating a new merge request by clicking the -**New merge request** button on the **merge requests** page in a project. -Then 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 -[**New merge request** page](#new-merge-request-page) and fill in the details. +A merge request is created. -## New merge request from a fork +### Add attachments when creating a merge request by email -After forking a project and applying your local changes, complete the following steps to -create a merge request from your fork to contribute back to the main project: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. -1. On the top bar, select **Menu > Project**. -1. Select **Your Projects**, then select your fork of the repository. -1. In the left menu, go to **Merge requests**, and click **New merge request**. -1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. -1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. - You can set a [default target project](#set-the-default-target-project) to - change the default target branch (which can be useful when working with a - forked project). -1. After entering the credentials, click **Compare branches and continue** to compare your local changes to the upstream repository. -1. Assign a user to review your changes, and click **Submit merge request**. +You can add commits to a merge request by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` are considered patches and are processed +ordered by name. -When the changes are merged, your changes are added to the upstream repository and -the branch as per specification. After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can unlink your -fork from its upstream project in the **Settings > Advanced Settings** section by -[removing the forking relationship](../settings/index.md#removing-a-fork-relationship). +The combined size of the patches can be 2 MB. -For further details, [see the forking workflow documentation](../repository/forking_workflow.md). +If the source branch from the subject does not exist, it is +created from the repository's HEAD or the specified target branch. +You can specify the target branch by using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches are applied on top of it. ## Set the default target project -Merge requests have a source and a target project which are the same, unless +Merge requests have a source and a target project that are the same, unless forking is involved. Creating a fork of the project can cause either of these scenarios when you create a new merge request: @@ -197,57 +163,11 @@ scenarios when you create a new merge request: option). - You target your own fork. -If you want to have merge requests from a fork by default target your own fork -(instead of the upstream project), you can change the default by: +To have merge requests from a fork by default target your own fork +(instead of the upstream project), you can change the default. -1. In your project, go to **Settings > General > Merge requests**. +1. On the top bar, select **Menu > Project**. +1. On the left menu, select **Settings > General > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. - -## New merge request by email **(FREE SELF)** - -_This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available._ It isn't -available in 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 is -used as the source branch name for the new merge request and the target branch -is the default branch for the project. The message body (if not empty) -is 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 has 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` are considered patches and they are processed -ordered by name. - -The combined size of the patches can be 2MB. - -If the source branch from the subject does not exist, it is -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 are applied on top of it. - -## Reviewing and managing merge requests - -Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 57850ad7304..a91679ffd63 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -79,9 +79,9 @@ draft merge requests: ## Pipelines for drafts -When the [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +When the [pipelines for merged results](../../../ci/pipelines/pipelines_for_merged_results.md) feature is enabled, draft merge requests run -[merge request pipelines](../../../ci/merge_request_pipelines/index.md) only. +[merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) only. To run pipelines for merged results, you must [mark the merge request as ready](#mark-merge-requests-as-ready). diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 68a63aebb90..15ab2d9c8e2 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -19,7 +19,7 @@ that it believes to be relevant to the input files. `tff` is designed for Ruby on Rails projects, so the `Verify/FailFast` template is configured to run when changes to Ruby files are detected. By default, it runs in -the [`.pre` stage](../../../ci/yaml/README.md#pre-and-post) of a GitLab CI/CD pipeline, +the [`.pre` stage](../../../ci/yaml/index.md#pre-and-post) of a GitLab CI/CD pipeline, before all other stages. ## Example use case @@ -42,8 +42,8 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) -- [Pipelines for Merged Results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results) + - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) +- [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. @@ -62,7 +62,7 @@ rspec-complete: - bundle exec rspec ``` -To run the most relevant specs first instead of the whole suite, [`include`](../../../ci/yaml/README.md#include) +To run the most relevant specs first instead of the whole suite, [`include`](../../../ci/yaml/index.md#include) the template by adding the following to your CI/CD configuration: ```yaml diff --git a/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png b/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png Binary files differnew file mode 100644 index 00000000000..e60e869f854 --- /dev/null +++ b/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png Binary files differindex a942420d65e..da7d4115bd9 100644 --- a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png Binary files differdeleted file mode 100644 index 14eef473e27..00000000000 --- a/doc/user/project/merge_requests/img/create_from_email.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png b/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png Binary files differdeleted file mode 100644 index bcbee10e1b7..00000000000 --- a/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png b/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png Binary files differdeleted file mode 100644 index c0f2ba261cb..00000000000 --- a/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png b/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png Binary files differnew file mode 100644 index 00000000000..4f49fad10ad --- /dev/null +++ b/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png diff --git a/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png b/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png Binary files differnew file mode 100644 index 00000000000..de61ca8b553 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png b/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png Binary files differnew file mode 100644 index 00000000000..c4e606bd2f4 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index b5c51c42ae9..fa90cf524ec 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,13 +27,13 @@ important parts of the merge request:  - **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolvable-comments-and-threads) + discussion area for [comment threads](../../discussions/index.md#resolve-a-thread)) and [code suggestions](reviews/suggestions.md). The right sidebar provides fields to add assignees, reviewers, labels, and a milestone to your work, and the [merge request widgets area](widgets.md) reports results from pipelines and tests. - **Commits**: Contains a list of commits added to this merge request. For more information, read [Commits tab in merge requests](commits.md). -- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/README.md) +- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/index.md) pipelines and their status. - **Changes**: Contains the diffs of files changed by this merge request. You can [configure the display](changes.md). @@ -119,7 +119,7 @@ For a software developer working in a team: 1. Pushes a commit with their final review. 1. [Approves the merge request](approvals/index.md). 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 changes get deployed to production with [manual actions](../../../ci/yaml/index.md#whenmanual) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. For a web developer writing a webpage for your company's website: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index d1b697add08..7ea785c00ea 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. With Load Performance Testing, you can test the impact of any pending code changes -to your application's backend in [GitLab CI/CD](../../../ci/README.md). +to your application's backend in [GitLab CI/CD](../../../ci/index.md). GitLab uses [k6](https://k6.io/), a free and open source tool, for measuring the system performance of applications under @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -93,7 +93,7 @@ template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../../ci/runners/README.md#linux-shared-runners) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/build_cloud/linux_build_cloud.md) likely have insufficient specs to handle most large k6 tests. This template runs the @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 21282a55ff2..aace1f58c62 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -27,7 +27,7 @@ the other way around. imports the library. - Prevent a documentation-only merge request from being merged before the merge request implementing the feature to be documented. -- Require an merge request updating a permissions matrix to be merged before merging an +- Require a merge request updating a permissions matrix to be merged before merging a merge request from someone who hasn't yet been granted permissions. It is common for a single logical change to span several merge requests, spread 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 6c1e33a9ace..d7c9c0f73ee 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -21,7 +21,7 @@ request is updated to show the impending merge. If you can't wait for the pipeline to succeed, you can choose **Merge immediately** in the dropdown menu on the right of the main button. -The author of the merge request and project members with developer permissions can +The author of the merge request and project members with the Developer role can cancel the automatic merge at any time before the pipeline finishes.  @@ -67,8 +67,8 @@ You should be careful to configure CI/CD so that pipelines run for every merge r ### Limitations When this setting is enabled, a merge request is prevented from being merged if there -is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#only--except) -or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines. +is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/index.md#only--except) +or [`rules`](../../../ci/yaml/index.md#rules) are used and they don't generate any pipelines. You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) and that it's successful. @@ -101,7 +101,7 @@ for details on avoiding two pipelines for a single merge request. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/README.md#skip-pipeline) prevent +When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/index.md#skip-pipeline) prevent merge requests from being merged. To change this behavior: 1. Navigate to your project's **Settings > General** page. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 317202e9303..16267e13fd5 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -100,7 +100,7 @@ When you submit your review, GitLab: ### Resolving/Unresolving threads -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolvable-comments-and-threads). +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). When replying to a comment, a checkbox is displayed to resolve or unresolve the thread after publication. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 9409cc569a6..8ee068531c8 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -14,7 +14,7 @@ type: index, reference As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request diff threads. Then, the merge request author (or other users with appropriate [permission](../../../permissions.md)) is able to apply these suggestions with a click, -which generates a commit in the merge request authored by the user that applied them. +which generates a commit in the merge request authored by the user that suggested the changes. 1. Choose a line of code to be changed, add a new comment, then select the **Insert suggestion** icon in the toolbar: @@ -42,7 +42,7 @@ which generates a commit in the merge request authored by the user that applied After the author applies a suggestion, it's marked with the **Applied** label, the thread is automatically resolved, and GitLab creates a new commit and pushes the suggested change directly into the codebase in the merge request's -branch. [Developer permission](../../../permissions.md) is required to do so. +branch. The [Developer role](../../../permissions.md) is required to do so. ## Multi-line suggestions diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 775820870f3..70e2d718406 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -8,11 +8,8 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/statu # External Status Checks **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)** +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -113,6 +110,31 @@ To complete the deletion of the status check you must select the **Remove status check** button. This **permanently** deletes the status check and it **will not** be recoverable. +## Status checks widget + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. + +The status checks widget displays in merge requests and shows the status of external +status checks: + + + +An organization might have a policy that does not allow merging merge requests if +external status checks do not pass. However, the details in the widget are for informational +purposes only. GitLab does not prevent merging of merge requests that fail status checks. + +While GitLab waits for a response from the external status check, the widget shows +the status checks as `pending`: + + + +After GitLab [receives a response](../../../api/status_checks.md#set-approval-status-of-an-external-status-check) +from the external status check, the widget updates accordingly. + +NOTE: +GitLab cannot guarantee that the external status checks are properly processed by +the related external service. + ## Troubleshooting ### Duplicate value errors @@ -149,30 +171,18 @@ An unexpected response was received from the branches retrieval API. As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. -## Enable or disable status checks **(ULTIMATE SELF)** - -Status checks are under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +### Failed to load status checks -To enable it: - -```ruby -# For the instance -Feature.enable(:ff_compliance_approval_gates) -# For a single project -Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +```plaintext +Failed to load status checks ``` -To disable it: +An unexpected response was received from the external status checks API. +You should: -```ruby -# For the instance -Feature.disable(:ff_compliance_approval_gates) -# For a single project -Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) -``` +- Refresh the page in case this error is temporary. +- Check the [GitLab status page](https://status.gitlab.com/) if the problem persists, + to see if there is a wider outage. ## Related links diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index e044d50d246..ce8bfa2d054 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -10,7 +10,7 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. -With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test +With the help of [GitLab CI/CD](../../../ci/index.md), you can collect the test coverage information of your favorite testing or coverage-analysis tool, and visualize this information inside the file diff view of your merge requests (MRs). This will allow you to see which lines are covered by tests, and which lines still require coverage, before the @@ -21,14 +21,14 @@ MR is merged. ## How test coverage visualization works Collecting the coverage information is done via GitLab CI/CD's -[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). +[artifacts reports feature](../../../ci/yaml/index.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab then takes the coverage information in all the files and combines it together. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/README.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/index.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -129,7 +129,7 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ### JavaScript example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: @@ -147,7 +147,7 @@ test: #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -185,7 +185,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -223,7 +223,7 @@ coverage-jdk11: ### Python example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. The information isn't displayed without the conversion. This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: @@ -243,7 +243,7 @@ run tests: ### C/C++ example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for C/C++ with +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with `gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage output file in Cobertura XML format. diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index 55e122dec76..0a9a2a37bfe 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -17,13 +17,13 @@ or link to useful information directly from merge requests: | [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](load_performance_testing.md) **(PREMIUM)** | Quickly determine the server performance impact of pending code changes. | | [Code Quality](code_quality.md) | 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](../../../ci/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. | +| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | | [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit 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. | | [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | | [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. | +| [Multi-Project pipelines](../../../ci/pipelines/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/pipelines/merge_request_pipelines.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/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | | [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index 92b2a8f24ef..b0464f3f972 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -14,7 +14,7 @@ and the services you configure for your project. ## Pipeline information -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +If you've set up [GitLab CI/CD](../../../ci/index.md) in your project, a [merge request](index.md) displays pipeline information in the widgets area of the **Overview** tab: @@ -62,3 +62,9 @@ merge request widget takes you directly to the pages changed, making it easier a faster to preview proposed modifications. [Read more about Review Apps](../../../ci/review_apps/index.md). + +## External status checks **(ULTIMATE)** + +If you have configured [external status checks](status_checks.md) you can +see the status of these checks in merge requests +[in a specific widget](status_checks.md#status-checks-widget). diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md deleted file mode 100644 index 8b663b8edf8..00000000000 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'drafts.md' -remove_date: '2021-05-19' ---- - -This document was moved to [another location](drafts.md). - -<!-- This redirect file can be deleted after <2021-05-19>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md deleted file mode 100644 index 55fde63dd47..00000000000 --- a/doc/user/project/new_ci_build_permissions_model.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../ci/README.md' -remove_date: '2021-06-01' ---- - -This document is deprecated. See the latest [GitLab CI/CD documentation](../../ci/README.md). - -<!-- This redirect file can be deleted after <2021-06-01>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 9f80e2e7613..eb5f3a1bbf0 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -4,40 +4,54 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Create a GitLab Pages website from scratch **(FREE)** +# Tutorial: Create a GitLab Pages website from scratch **(FREE)** -This tutorial shows you how to create a Pages site from scratch. You start with -a blank project and create your own CI file, which gives instruction to -a [runner](https://docs.gitlab.com/runner/). When your CI/CD +This tutorial shows you how to create a Pages site from scratch using +the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). You start with +a blank project and create your own CI/CD configuration file, which gives +instructions to a [runner](https://docs.gitlab.com/runner/). When your CI/CD [pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. -This example uses the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). -Other SSGs follow similar steps. You do not need to be familiar with Jekyll or SSGs +This example uses Jekyll, but other SSGs follow similar steps. +You do not need to be familiar with Jekyll or SSGs to complete this tutorial. +To create a GitLab Pages website: + +- [Step 1: Create the project files](#create-the-project-files) +- [Step 2: Choose a Docker image](#choose-a-docker-image) +- [Step 3: Install Jekyll](#install-jekyll) +- [Step 4: Specify the `public` directory for output](#specify-the-public-directory-for-output) +- [Step 5: Specify the `public` directory for artifacts](#specify-the-public-directory-for-artifacts) +- [Step 6: Deploy and view your website](#deploy-and-view-your-website) + ## Prerequisites -To follow along with this example, start with a blank project in GitLab. -Create three files in the root (top-level) directory. +You must have a [blank project](../../working_with_projects.md#blank-projects) in GitLab. -- `.gitlab-ci.yml` A YAML file that contains the commands you want to run. - For now, leave the file's contents blank. +## Create the project files -- `index.html` An HTML file you can populate with whatever HTML content you'd like, - for example: +Create three files in the root (top-level) directory: - ```html - <html> - <head> - <title>Home</title> - </head> - <body> - <h1>Hello World!</h1> - </body> - </html> - ``` +- `.gitlab-ci.yml`: A YAML file that contains the commands you want to run. + For now, leave the file's contents blank. + +- `index.html`: An HTML file you can populate with whatever HTML content + you'd like, for example: + + ```html + <html> + <head> + <title>Home</title> + </head> + <body> + <h1>Hello World!</h1> + </body> + </html> + ``` + +- [`Gemfile`](https://bundler.io/gemfile.html): A file that describes dependencies for Ruby programs. -- [`Gemfile`](https://bundler.io/gemfile.html) A file that describes dependencies for Ruby programs. Populate it with this content: ```ruby @@ -53,7 +67,7 @@ to run scripts and deploy the site. This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/ruby). -Edit your `.gitlab-ci.yml` and add this text as the first line. +Edit your `.gitlab-ci.yml` file and add this text as the first line: ```yaml image: ruby:2.7 @@ -65,13 +79,15 @@ image that contains NodeJS as part of its file system. For example, for a ## Install Jekyll -To run [Jekyll](https://jekyllrb.com/) locally, you would open your terminal and: +To run [Jekyll](https://jekyllrb.com/) locally, you must install it: -- Install [Bundler](https://bundler.io/) by running `gem install bundler`. -- Create `Gemfile.lock` by running `bundle install`. -- Install Jekyll by running `bundle exec jekyll build`. +1. Open your terminal. +1. Install [Bundler](https://bundler.io/) by running `gem install bundler`. +1. Create `Gemfile.lock` by running `bundle install`. +1. Install Jekyll by running `bundle exec jekyll build`. -In the `.gitlab-ci.yml` file, this is written as: +To run Jekyll in your project, edit the `.gitlab-ci.yml` file +and add the installation commands: ```yaml script: @@ -109,7 +125,8 @@ pages: Jekyll needs to know where to generate its output. GitLab Pages only considers files in a directory called `public`. -Jekyll uses destination (`-d`) to specify an output directory for the built website: +Jekyll uses a destination flag (`-d`) to specify an output directory for the built website. +Add the destination to your `.gitlab-ci.yml` file: ```yaml pages: @@ -136,7 +153,7 @@ pages: - public ``` -Paste this into `.gitlab-ci.yml` file, so it now looks like this: +Your `.gitlab-ci.yml` file should now look like this: ```yaml image: ruby:2.7 @@ -151,23 +168,29 @@ pages: - public ``` -Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run -by going to **CI/CD > Pipelines**. +## Deploy and view your website -When it succeeds, go to **Settings > Pages** to view the URL where your site -is now available. +After you have completed the preceding steps, +deploy your website: + +1. Save and commit the `.gitlab-ci.yml` file. +1. Go to **CI/CD > Pipelines** to watch the pipeline. +1. When the pipeline succeeds, go to **Settings > Pages** + to view the URL where your site is now available. + +When this `pages` job completes successfully, a special `pages:deploy` job +appears in the pipeline view. It prepares the content of the website for the +GitLab Pages daemon. GitLab runs it in the background and doesn't use a runner. + +## Other options for your CI/CD file If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file -with [any of the available settings](../../../../ci/yaml/README.md). You can validate +with [any of the available settings](../../../../ci/yaml/index.md). You can validate your `.gitlab-ci.yml` file with the [CI Lint](../../../../ci/lint.md) tool that's included with GitLab. -After successful execution of this `pages` job, a special `pages:deploy` job appears in the -pipeline view. It prepares the content of the website for GitLab Pages daemon. GitLab executes it in -the background and doesn't use runner. - The following topics show other examples of other options you can add to your CI/CD file. -## Deploy specific branches to a Pages site +### Deploy specific branches to a Pages site You may want to deploy to a Pages site only from specific branches. @@ -191,7 +214,8 @@ pages: - public ``` -Then configure the pipeline to run the job for the `master` branch only. +Then configure the pipeline to run the job for the +[default branch](../../repository/branches/default.md) (here, `main`) only. ```yaml image: ruby:2.7 @@ -209,17 +233,17 @@ pages: paths: - public rules: - - if: '$CI_COMMIT_BRANCH == "master"' + - if: '$CI_COMMIT_BRANCH == "main"' ``` -## Specify a stage to deploy +### Specify a stage to deploy There are three default stages for GitLab CI/CD: build, test, and deploy. If you want to test your script and check the built site before deploying to production, you can run the test exactly as it runs when you -push to `master`. +push to your [default branch](../../repository/branches/default.md) (here, `main`). To specify a stage for your job to run in, add a `stage` line to your CI file: @@ -241,11 +265,11 @@ pages: paths: - public rules: - - if: '$CI_COMMIT_BRANCH == "master"' + - if: '$CI_COMMIT_BRANCH == "main"' ``` Now add another job to the CI file, telling it to -test every push to every branch **except** the `master` branch: +test every push to every branch **except** the `main` branch: ```yaml image: ruby:2.7 @@ -264,7 +288,7 @@ pages: paths: - public rules: - - if: '$CI_COMMIT_BRANCH == "master"' + - if: '$CI_COMMIT_BRANCH == "main"' test: stage: test @@ -276,19 +300,19 @@ test: paths: - test rules: - - if: '$CI_COMMIT_BRANCH != "master"' + - if: '$CI_COMMIT_BRANCH != "main"' ``` When the `test` job runs in the `test` stage, Jekyll builds the site in a directory called `test`. The job affects -all branches except `master`. +all branches except `main`. When you apply stages to different jobs, every job in the same stage builds in parallel. If your web application needs more than one test before being deployed, you can run all your tests at the same time. -## Remove duplicate commands +### Remove duplicate commands To avoid duplicating the same scripts in every job, you can add them to a `before_script` section. @@ -317,7 +341,7 @@ pages: paths: - public rules: - - if: '$CI_COMMIT_BRANCH == "master"' + - if: '$CI_COMMIT_BRANCH == "main"' test: stage: test @@ -327,10 +351,10 @@ test: paths: - test rules: - - if: '$CI_COMMIT_BRANCH != "master"' + - if: '$CI_COMMIT_BRANCH != "main"' ``` -## Build faster with cached dependencies +### Build faster with cached dependencies To build faster, you can cache the installation files for your project's dependencies by using the `cache` parameter. @@ -361,7 +385,7 @@ pages: paths: - public rules: - - if: '$CI_COMMIT_BRANCH == "master"' + - if: '$CI_COMMIT_BRANCH == "main"' test: stage: test @@ -371,7 +395,7 @@ test: paths: - test rules: - - if: '$CI_COMMIT_BRANCH != "master"' + - if: '$CI_COMMIT_BRANCH != "main"' ``` In this case, you need to exclude the `/vendor` @@ -386,10 +410,11 @@ exclude: - vendor ``` -Now GitLab CI/CD not only builds the website, -but also pushes with **continuous tests** to feature-branches, -**caches** dependencies installed with Bundler, and -**continuously deploys** every push to the `master` branch. +Now GitLab CI/CD not only builds the website, but also: + +- Pushes with **continuous tests** to feature branches. +- **Caches** dependencies installed with Bundler. +- **Continuously deploys** every push to the `main` branch. ## Related topics diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 1f5e1a6ab45..5a688fbb485 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -78,7 +78,7 @@ GitLab always deploys your website from a very specific folder called `public` i repository. When you create a new project in GitLab, a [repository](../repository/index.md) becomes available automatically. -To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/README.md) +To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/index.md) to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md). diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 4d6a8653657..94656c91e98 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -22,7 +22,7 @@ In brief, this is what you need to upload your website in GitLab Pages: 1. Domain of the instance: domain name that is used for GitLab Pages (ask your administrator). -1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/README.md#pages) in the root directory of your repository. +1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/index.md#pages) in the root directory of your repository. 1. A directory called `public` in your site's repository containing the content to be published. 1. GitLab Runner enabled for the project. @@ -129,7 +129,7 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit -the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#only--except), +the `pages` job with the [`only` parameter](../../../ci/yaml/index.md#only--except), whenever a new commit is pushed to a branch used specifically for 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 ce49699785e..978e35b3a9f 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -60,7 +60,7 @@ might be slightly different. Follow the sudo certbot certonly -a manual -d example.com --email your@email.com ``` - Alternatively, you can register without adding an e-mail account, + Alternatively, you can register without adding an email account, but you aren't notified about the certificate expiration's date: ```shell diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 4b77236f808..4ff651891b2 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -13,24 +13,24 @@ further restrictions on certain branches, they can be protected. The default branch for your repository is protected by default. -## Who can access a protected branch +## Who can modify a protected branch -When a branch is protected, the default behavior enforces -these restrictions on the branch. +When a branch is protected, the default behavior enforces these restrictions on the branch. -| Action | Who can do it | -|--------------------------|---------------| -| Protect a branch | Maintainers only. | -| Push to the branch | GitLab administrators and anyone with **Allowed** permission. (*) | -| Force push to the branch | No one. | -| Delete the branch | No one. | +| Action | Who can do it | +|:-------------------------|:------------------------------------------------------------------| +| Protect a branch | Maintainers only. | +| Push to the branch | GitLab administrators and anyone with **Allowed** permission. (1) | +| Force push to the branch | No one. | +| Delete the branch | No one. | -(*) Users with developer permissions can create a project in a group, -but might not be allowed to initially push to the [default branch](repository/branches/default.md). +1. Users with the Developer role can create a project in a group, but might not be allowed to + initially push to the [default branch](repository/branches/default.md). -### Set the branch protection default level +### Set the default branch protection level -The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +Administrators can set a default branch protection level in the +[Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). ## Configure a protected branch @@ -43,140 +43,108 @@ To protect a branch: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. -The protected branch displays in the **Protected branches** list. +The protected branch displays in the list of protected branches. -## Using the Allowed to merge and Allowed to push settings +## Configure multiple protected branches by using a wildcard -In GitLab 8.11 and later, we added another layer of branch protection which provides -more granular management of protected branches. The **Developers can push** -option was replaced by **Allowed to push**. You can set this value to allow -or prohibit Maintainers and/or Developers to push to a protected branch. - -Using the **Allowed to push** and **Allowed to merge** settings, you can control -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](../../topics/gitlab_flow.md). - -However, there are workflows where that is not needed, and only protecting from -force pushes and branch removal is useful. For those workflows, you can allow -everyone with write access to push to a protected branch by setting -**Allowed to push** to "Developers + Maintainers". - -You can set the **Allowed to push** and **Allowed to merge** options while creating -a protected branch or afterwards by selecting the option you want from the -dropdown list in the **Already protected** area. - - - -If you don't choose any of those options while creating a protected branch, -they are set to Maintainers by default. - -### Allow deploy keys to push to a protected branch - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. -> - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users. -> - This feature is available for all users in GitLab 13.9. - -You can allow specific machines to access protected branches in your repository with -[deploy keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, -for example. - -Deploy keys can be selected in the **Allowed to push** dropdown when: +Prerequisite: -- Defining a protected branch. -- Updating an existing branch. +- You must have at least the [Maintainer role](../permissions.md). -Select a deploy key to allow the key's owner to push to the chosen protected branch, -even if they aren't a member of the related project. The owner of the selected deploy -key must have at least read access to the given project. +To protect multiple branches at the same time: -For a deploy key to be selectable: +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, type the branch name and a wildcard. + For example: -- It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). -- It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. + | Wildcard protected branch | Matching branches | + |---------------------------|--------------------------------------------------------| + | `*-stable` | `production-stable`, `staging-stable` | + | `production/*` | `production/app-server`, `production/load-balancer` | + | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -Deploy keys are not available in the **Allowed to merge** dropdown. +1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +1. Select **Protect**. - +The protected branch displays in the list of protected branches. -## Restricting push and merge access to certain users **(PREMIUM)** +## Create a protected branch -With GitLab Premium you can restrict access to protected branches -by choosing a role (Maintainers, Developers) and certain users. From the -dropdown menu select the role and/or the users you want to have merge or push -access. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. - +Users with the Developer or higher [role](../permissions.md) can create a protected branch. -Click **Protect** and the branch displays in the **Protected branch** list. +Prerequisites: - +- **Allowed to push** is set to **No one** +- **Allowed to merge** is set to **Developers**. -## Wildcard protected branches +You can create a protected branch by using the UI or API only. +This prevents you from accidentally creating a branch +from the command line or from a Git client application. -You can specify a wildcard protected branch, which protects all branches -matching the wildcard. For example: +To create a new branch through the user interface: -| Wildcard Protected Branch | Matching Branches | -|---------------------------|--------------------------------------------------------| -| `*-stable` | `production-stable`, `staging-stable` | -| `production/*` | `production/app-server`, `production/load-balancer` | -| `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | +1. Go to **Repository > Branches**. +1. Select **New branch**. +1. Fill in the branch name and select an existing branch, tag, or commit to + base the new branch on. Only existing protected branches and commits + that are already in protected branches are accepted. -Protected branch settings, like **Developers can push**, apply to all matching -branches. +## Require everyone to submit merge requests for a protected branch -Two different wildcards can potentially match the same branch. For example, -`*-stable` and `production-*` would both match a `production-stable` branch. -In that case, if _any_ of these protected branches have a setting like -"Allowed to push", then `production-stable` also inherit this setting. +You can force everyone to submit a merge request, rather than allowing them to check in directly +to a protected branch. This is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). -If you click on a protected branch's name, GitLab displays a list of -all matching branches: +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Allowed to merge** list, select **Developers + Maintainers**. +1. From the **Allowed to push** list, select **No one**. +1. Select **Protect**. - +## Allow everyone to push directly to a protected branch -## Create a protected branch +You can allow everyone with write access to push to the protected branch. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Allowed to push** list, select **Developers + Maintainers**. +1. Select **Protect**. -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 as long as they are -[**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). -This can only be done by using the UI or through the API, to avoid creating protected -branches accidentally from the command line or from a Git client application. +## Allow deploy keys to push to a protected branch -To create a new branch through the user interface: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. +> - This feature was selectively deployed in GitLab.com 13.7, and may not be available for all users. +> - This feature is available for all users in GitLab 13.9. -1. Go to **Repository > Branches**. -1. Click on **New branch**. -1. Fill in the branch name and select an existing branch, tag, or commit to - base the new branch on. Only existing protected branches and commits - that are already in protected branches are accepted. +You can permit the owner of a [deploy key](deploy_keys/index.md) to push to a protected branch. +The deploy key works, even if the user isn't a member of the related project. However, the owner of the deploy +key must have at least read access to the project. -## Delete a protected branch +Prerequisites: -From time to time, you may need to delete or clean up protected branches. -User with the [Maintainer role](../permissions.md) and greater can manually delete protected -branches by using the GitLab web interface: +- The deploy key must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). +- The deploy key must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. -1. Go to **Repository > Branches**. -1. Click on the delete icon next to the branch you wish to delete. -1. To prevent accidental deletion, an additional confirmation is required. +To allow a deploy key to push to a protected branch: -  +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Allowed to push** list, select the deploy key. +1. Select **Protect**. -Deleting a protected branch is allowed only by using the web interface; not from Git. -This means that you can't accidentally delete a protected branch from your -command line or a Git client application. +Deploy keys are not available in the **Allowed to merge** dropdown. -## Allow force push on protected branches +## Allow force push on a protected branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. @@ -185,68 +153,74 @@ WARNING: This feature might not be available to you. Check the **version history** note above for details. You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to -protected branches by either setting **Allowed to force push** -when you protect a new branch, or by configuring an already-protected branch. +protected branches. -To protect a new branch and enable Force push: +To protect a new branch and enable force push: -1. Navigate to your project's **Settings > Repository**. -1. Expand **Protected branches**, and scroll to **Protect a branch**. -1. Select a **Branch** or wildcard you'd like to protect. -1. Select the user levels **Allowed to merge** and **Allowed to push**. -1. To allow all users with push access to force push, toggle the **Allowed to force push** slider. -1. To reject code pushes that change files listed in the `CODEOWNERS` file, toggle - **Require approval from code owners**. -1. Click **Protect**. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. +1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. +1. To reject code pushes that change files listed in the `CODEOWNERS` file, turn on the + **Require approval from code owners** toggle. +1. Select **Protect**. -To enable force pushes on branches already protected: +To enable force pushes on branches that are already protected: -1. Navigate to your project's **Settings > Repository**. -1. Expand **Protected branches** and scroll to **Protected branch**. -1. Toggle the **Allowed to force push** slider for the chosen branch. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. -When enabled, members who are allowed to push to this branch can also force push. +When enabled, members who are can push to this branch can also force push. -## Protected branches approval by Code Owners **(PREMIUM)** +## Require Code Owner approval on a protected branch **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. +> - [In](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5 and later, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. -It is possible to require at least one approval by a -[Code Owner](code_owners.md) to a file changed by the -merge request. You can either set Code Owners approvals -at the time you protect a new branch, or set it to a branch -already protected, as described below. +You can require at least one approval by a [Code Owner](code_owners.md) to a file changed by the +merge request. To protect a new branch and enable Code Owner's approval: -1. Navigate to your project's **Settings > Repository** and expand **Protected branches**. -1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider. -1. Click **Protect**. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. +1. Turn on the **Require approval from code owners** toggle. +1. Select **Protect**. -To enable Code Owner's approval to branches already protected: +To enable Code Owner's approval on branches that are already protected: -1. Navigate to your project's **Settings > Repository** and expand **Protected branches**. -1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle. -When enabled, all merge requests targeting these branches require approval +When enabled, all merge requests for these branches require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules. +## Run pipelines on protected branches -## Running pipelines on protected branches - -The permission to merge or push to protected branches is used to define if a user can -run CI/CD pipelines and execute actions on jobs that are related to those branches. +The permission to merge or push to protected branches defines +whether or not a user can run CI/CD pipelines and execute actions on jobs. See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. -## Changelog +## Delete a protected branch + +Users with the [Maintainer role](../permissions.md) and greater can manually delete protected +branches by using the GitLab web interface: + +1. Go to **Repository > Branches**. +1. Next to the branch you want to delete, select the **Delete** button (**{remove}**). +1. On the confirmation dialog, type the branch name and select **Delete protected branch**. -- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). -- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) - by Developers (and users with higher permission levels) through the API and the user interface. +You can delete a protected branch from the UI only. +This prevents you from accidentally deleting a branch +from the command line or from a Git client application. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 17a9cd5c8c6..b4e13aebdb2 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -9,15 +9,24 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. -Protected tags allow control over who has permission to create tags as well as preventing accidental update or deletion once created. Each rule allows you to match either an individual tag name, or use wildcards to control multiple tags at once. +Protected tags: + +- Allow control over who has permission to create tags. +- Prevent accidental update or deletion once created. + +Each rule allows you to match either: + +- An individual tag name. +- Wildcards to control multiple tags at once. This feature evolved out of [protected branches](protected_branches.md) -## Overview +## Who can modify a protected tag + +By default: -Protected tags prevent anyone from updating or deleting the tag, and prevent -creation of matching tags based on the permissions you have selected. By default, -anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags. +- To create tags, you must have the [Maintainer role](../permissions.md). +- No one can update or delete tags. ## Configuring protected tags diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 728c682b009..c17133e72cf 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -39,7 +39,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: @@ -66,6 +66,7 @@ time as pushing changes: | `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | +| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. Ex: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 45cb5e74d6c..d8d464ce6d8 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -69,11 +69,11 @@ threads. Some quick actions might not be available to all subscription tiers. | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | | `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants`. | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | | `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | | `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | -| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | | `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | | `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 71cbff9e545..3a25b148fdf 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -14,8 +14,11 @@ To introduce a checkpoint in your source code history, you can assign a However, in most cases, your users need more than just the raw source code. They need compiled objects or other assets output by your CI/CD system. -A GitLab *Release* is a snapshot of the source, build output, artifacts, and other metadata -associated with a released version of your code. +A GitLab Release can be: + +- A snapshot of the source code of your repository. +- [Generic packages](../../packages/generic_packages/index.md) created from job artifacts. +- Other metadata associated with a released version of your code. You can create a GitLab release on any branch. When you create a release: @@ -59,8 +62,8 @@ You can create a release in the user interface, or by using the We recommend using the API to create releases as one of the last steps in your CI/CD pipeline. -Only users with Developer permissions or higher can create releases. -Read more about [Release permissions](../../../user/permissions.md#project-members-permissions). +Only users with at least the Developer role can create releases. +Read more about [Release permissions](#release-permissions). To create a new release through the GitLab UI: @@ -79,7 +82,7 @@ To create a new release through the GitLab UI: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. -You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/README.md#release) +You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/index.md#release) by using a `release` node in the job definition. The release is created only if the job processes without error. If the Rails API returns an error @@ -99,8 +102,8 @@ release tag. When the `released_at` date and time has passed, the badge is autom > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. -Only users with Developer permissions or higher can edit releases. -Read more about [Release permissions](../../../user/permissions.md#project-members-permissions). +Only users with at least the Developer can edit releases. +Read more about [Release permissions](#release-permissions). To edit the details of a release: @@ -242,7 +245,7 @@ but are _not_ allowed to view details about the Git repository (in particular, tag names). Because of this, release titles are replaced with a generic title like "Release-1234" for Guest users to avoid leaking tag name information. -See the [Permissions](../../permissions.md#project-members-permissions) page for +See the [Release permissions](#release-permissions) section for more information about permissions. ### Tag name @@ -273,14 +276,28 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m A release contains the following types of assets: - [Source code](#source-code) -- [Permanent links to release assets](#permanent-links-to-release-assets) +- [Link](#links) #### Source code GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` archived source code from the given Git tag. These are read-only assets. -#### Permanent links to release assets +#### Links + +A link is any URL which can point to whatever you like: documentation, built +binaries, or other related materials. These can be both internal or external +links from your GitLab instance. +Each link as an asset has the following attributes: + +| Attribute | Description | Required | +| ---- | ----------- | --- | +| `name` | The name of the link. | Yes | +| `url` | The URL to download a file. | Yes | +| `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | +| `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | + +##### Permanent links to release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. @@ -289,20 +306,6 @@ GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link). -Each asset has a `name`, a `url` of the *actual* asset location, and optionally, -`filepath` and `link_type` parameters. - -A `filepath` creates a URL pointing to the asset for the Release. - -The `link_type` parameter accepts one of the following four values: - -- `runbook` -- `package` -- `image` -- `other` (default) - -This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. - The format of the URL is: ```plaintext @@ -329,13 +332,104 @@ https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binar The physical location of the asset can change at any time and the direct link remains unchanged. -### Links +##### Link Types -A link is any URL which can point to whatever you like: documentation, built -binaries, or other related materials. These can be both internal or external -links from your GitLab instance. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. The four types of links are "Runbook," "Package," "Image," and "Other." +The `link_type` parameter accepts one of the following four values: + +- `runbook` +- `package` +- `image` +- `other` (default) + +This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. + +##### Use a generic package for attaching binaries + +You can use [generic packages](../../packages/generic_packages/index.md) +to store any artifacts from a release or tag pipeline, +that can also be used for attaching binary files to an individual release entry. +You basically need to: + +1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). +1. [Attach the package link to the release](#links). + +The following example generates release assets, publishes them +as a generic package, and then creates a release: + +```yaml +stages: + - build + - upload + - release + +variables: + # Package version can only contain numbers (0-9), and dots (.). + # Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion. + # See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file + PACKAGE_VERSION: "1.2.3" + DARWIN_AMD64_BINARY: "myawesomerelease-darwin-amd64-${PACKAGE_VERSION}" + LINUX_AMD64_BINARY: "myawesomerelease-linux-amd64-${PACKAGE_VERSION}" + PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/myawesomerelease/${PACKAGE_VERSION}" + +build: + stage: build + image: alpine:latest + rules: + - if: $CI_COMMIT_TAG + script: + - mkdir bin + - echo "Mock binary for ${DARWIN_AMD64_BINARY}" > bin/${DARWIN_AMD64_BINARY} + - echo "Mock binary for ${LINUX_AMD64_BINARY}" > bin/${LINUX_AMD64_BINARY} + artifacts: + paths: + - bin/ + +upload: + stage: upload + image: curlimages/curl:latest + rules: + - if: $CI_COMMIT_TAG + script: + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${DARWIN_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY} + - | + curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file bin/${LINUX_AMD64_BINARY} ${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY} + +release: + # Caution, as of 2021-02-02 these assets links require a login, see: + # https://gitlab.com/gitlab-org/gitlab/-/issues/299384 + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG + script: + - | + release-cli create --name "Release $CI_COMMIT_TAG" --tag-name $CI_COMMIT_TAG \ + --assets-link "{\"name\":\"${DARWIN_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}\"}" \ + --assets-link "{\"name\":\"${LINUX_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}\"}" +``` + +PowerShell users may need to escape the double quote `"` inside a JSON +string with a `` ` `` (back tick) for `--assets-link` and `ConvertTo-Json` +before passing on to the `release-cli`. +For example: + +```yaml +release: + script: + - $env:asset = "{`"name`":`"MyFooAsset`",`"url`":`"https://gitlab.com/upack/artifacts/download/$env:UPACK_GROUP/$env:UPACK_NAME/$($env:GitVersion_SemVer)?contentOnly=zip`"}" + - $env:assetjson = $env:asset | ConvertTo-Json + - release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson +``` + +NOTE: +Directly attaching [job artifacts](../../../ci/pipelines/job_artifacts.md) +links to a release is not recommended, because artifacts are ephemeral and +are used to pass data in the same pipeline. This means there's a risk that +they could either expire or someone might manually delete them. ## Release evidence @@ -428,14 +522,14 @@ Evidence collection snapshots are visible on the Releases page, along with the t > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. -When you create a release, if [job artifacts](../../../ci/yaml/README.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. +When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. Although job artifacts normally expire, artifacts included in release evidence do not expire. To enable job artifact collection you need to specify both: -1. [`artifacts:paths`](../../../ci/yaml/README.md#artifactspaths) -1. [`artifacts:reports`](../../../ci/yaml/README.md#artifactsreports) +1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths) +1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) ```yaml ruby: @@ -455,7 +549,7 @@ release evidence. If you [schedule release evidence collection](#schedule-release-evidence-collection), some artifacts may already be expired by the time of evidence collection. To avoid this you can use -the [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) +the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). ### Schedule release evidence collection @@ -471,6 +565,49 @@ In the API: - If you do not specify a `released_at` date, release evidence is collected on the date the release is created. +## Release permissions + +> [The permission model for create, update and delete actions was fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1. + +### View a release and download assets + +- Users with [Reporter role or above](../../../user/permissions.md#project-members-permissions) + have read and download access to the project releases. +- Users with [Guest role](../../../user/permissions.md#project-members-permissions) + have read and download access to the project releases, however, + repository-related information are redacted (for example the Git tag name). + +### Create, update, and delete a release and its assets + +- Users with [Developer role or above](../../../user/permissions.md#project-members-permissions) + have write access to the project releases and assets. +- If a release is associated with a [protected tag](../protected_tags.md), + the user must be [allowed to create the protected tag](../protected_tags.md#configuring-protected-tags) too. + +As an example of release permission control, you can allow only +[Maintainer role or above](../../../user/permissions.md#project-members-permissions) +to create, update, and delete releases by protecting the tag with a wildcard (`*`), +and set **Maintainer** in the **Allowed to create** column. + +#### Enable or disable protected tag evaluation on releases **(FREE SELF)** + +Protected tag evaluation on release permissions is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:evalute_protected_tag_for_release_permissions) +``` + +To disable it: + +```ruby +Feature.disable(:evalute_protected_tag_for_release_permissions) +``` + ## Release Command Line > [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. @@ -494,14 +631,13 @@ These metrics include: - Total number of releases in the group - Percentage of projects in the group that have at least one release -<!-- ## Troubleshooting +## Troubleshooting + +### Getting `403 Forbidden` or `Something went wrong while creating a new release` errors when creating, updating or deleting releases and their assets -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +If the release is associted with a [protected tag](../protected_tags.md), +the UI/API request might result in an authorization failure. +Make sure that the user or a service/bot account is allowed to +[create the protected tag](../protected_tags.md#configuring-protected-tags) too. -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. --> +See [the release permissions](#release-permissions) for more information. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 6c2469ac377..2f1171a7d4f 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -57,9 +57,7 @@ GitLab administrators can configure a new default branch name at the ### Instance-level custom initial branch name **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It cannot be enabled or disabled per-project. -> - It's recommended for production use. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/325163) in GitLab 13.12. GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual @@ -154,8 +152,45 @@ renames a Git repository's (`example`) default branch. 1. Update references to the old branch name in related code and scripts that reside outside your repository, such as helper utilities and integrations. +## Default branch rename redirect + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329100) in GitLab 14.1 + +URLs for specific files or directories in a project embed the project's default +branch name, and are often found in documentation or browser bookmarks. When you +[update the default branch name in your repository](#update-the-default-branch-name-in-your-repository), +these URLs change, and must be updated. + +To ease the transition period, whenever the default branch for a project is +changed, GitLab records the name of the old default branch. If that branch is +deleted, attempts to view a file or directory on it are redirected to the +current default branch, instead of displaying the "not found" page. + ## Resources - [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) on the Git mailing list - [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/) + +## Troubleshooting + +### Unable to change default branch: resets to current branch + +We are tracking this problem in [issue 20474](https://gitlab.com/gitlab-org/gitlab/-/issues/20474). +This issue often occurs when a branch named `HEAD` is present in the repository. +To fix the problem: + +1. In your local repository, create a new, temporary branch and push it: + + ```shell + git checkout -b tmp_default && git push -u origin tmp_default + ``` + +1. In GitLab, proceed to [change the default branch](#change-the-default-branch-name-for-a-project) to that temporary branch. +1. From your local repository, delete the `HEAD` branch: + + ```shell + git push -d origin HEAD + ``` + +1. In GitLab, [change the default branch](#change-the-default-branch-name-for-a-project) to the one you intend to use. diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md new file mode 100644 index 00000000000..4bf6c7451d5 --- /dev/null +++ b/doc/user/project/repository/csv.md @@ -0,0 +1,24 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# CSV files **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14174) in GitLab 14.1. + +A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. +Each line of the file is a data record. Each record consists of one or more fields, separated by +commas. The use of the comma as a field separator is the source of the name for this file format. +A CSV file typically stores tabular data (numbers and text) in plain text, in which case each line +will have the same number of fields. + +The CSV file format is not fully standardized. Other characters can be used as column delimiters. +Fields may or may not be surrounded to escape special characters. + +When added to a repository, files with a `.csv` extension are rendered as a table when viewed in +GitLab. + + diff --git a/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.png b/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.png Binary files differnew file mode 100644 index 00000000000..0f9b623e7b4 --- /dev/null +++ b/doc/user/project/repository/img/csv_file_rendered_as_table_v14_1.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 differdeleted file mode 100644 index a3e0b74ddf8..00000000000 --- a/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png +++ /dev/null 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 differdeleted file mode 100644 index 8e15b5a0784..00000000000 --- a/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png +++ /dev/null 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 differdeleted file mode 100644 index 8916d21d515..00000000000 --- a/doc/user/project/repository/img/repository_mirroring_push_settings.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 7919850b8cc..afdcf2a94fa 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -38,10 +38,10 @@ to a branch in the repository. When you use the command line, you can commit mul In GitLab, you can add keywords to the commit message to perform one of the following actions: - **Trigger a GitLab CI/CD pipeline:** - If the project is configured with [GitLab CI/CD](../../../ci/README.md), + If the project is configured with [GitLab CI/CD](../../../ci/index.md), you trigger a pipeline per push, not per commit. - **Skip pipelines:** - Add the [`ci skip`](../../../ci/yaml/README.md#skip-pipeline) keyword to + Add the [`ci skip`](../../../ci/yaml/index.md#skip-pipeline) keyword to your commit message to make GitLab CI/CD skip the pipeline. - **Cross-link issues and merge requests:** Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages) diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index e9f214f08ce..71bece03a33 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -11,13 +11,16 @@ Repository mirroring allows for the mirroring of repositories to and from extern can use it to mirror branches, tags, and commits between repositories. It helps you use a repository outside of GitLab. -A repository mirror at GitLab updates automatically. You can also manually trigger an update -at most once every five minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). +A repository mirror at GitLab updates automatically. You can also manually trigger an update: + +- At most once every five minutes on GitLab.com. +- According to a [limit set by the administrator](../../../administration/instance_limits.md#pull-mirroring-interval) + on self-managed instances. There are two kinds of repository mirroring supported by GitLab: -- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(FREE)** -- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(PREMIUM)** +- [Push](#push-to-a-remote-repository): for mirroring a GitLab repository to another location. +- [Pull](#pull-from-a-remote-repository): for mirroring a repository from another location to GitLab. When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. @@ -48,9 +51,9 @@ The following are some possible use cases for repository mirroring: GitLab.com repository that's public, allows you to open source specific projects and contribute back to the open source community. -## Pushing to a remote repository **(FREE)** +## Push to a remote repository -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. For an existing project, you can set up push mirroring as follows: @@ -63,8 +66,6 @@ For an existing project, you can set up push mirroring as follows: 1. Select the **Keep divergent refs** check box, if desired. 1. Select **Mirror repository** to save the configuration. - - When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the mirror diverging. @@ -72,7 +73,7 @@ Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodica The mirrored repository receives all changes only when: - Commits are pushed to GitLab. -- A [forced update](#forcing-an-update) is initiated. +- A [forced update](#force-an-update) is initiated. Changes pushed to files in the repository are automatically pushed to the remote mirror at least: @@ -82,14 +83,14 @@ Changes pushed to files in the repository are automatically pushed to the remote In the case of a diverged branch, an error displays in the **Mirroring repositories** section. -### Configuring push mirrors through the API +### Configure push mirrors through the API You can also create and modify project push mirrors through the [remote mirrors API](../../../api/remote_mirrors.md). ### Keep divergent refs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. By default, if any ref on the remote mirror has diverged from the local repository, the *entire push* fails, and no updates occur. @@ -108,11 +109,11 @@ update. NOTE: After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md). -### Setting up a push mirror from GitLab to GitHub +### Set up a push mirror from GitLab to GitHub To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) 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. Select **Mirror repository**. @@ -121,7 +122,7 @@ The mirrored repository is listed. For example, `https://*****:*****@github.com/ The repository pushes shortly thereafter. To force a push, select the **Update now** (**{retry}**) button. -### Setting up a push mirror from GitLab to AWS CodeCommit +### Set up a push mirror from GitLab to AWS CodeCommit AWS CodeCommit push mirroring is the best way to connect GitLab repositories to AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. @@ -203,7 +204,7 @@ To test mirroring by forcing a push, select the half-circle arrows button (hover If **Last successful update** shows a date, you have configured mirroring correctly. If it isn't working correctly, a red `error` tag appears and shows the error message as hover text. -### Setting up a push mirror to another GitLab instance with 2FA activated +### Set up a push mirror to another GitLab instance with 2FA activated 1. On the destination GitLab instance, create a [personal access token](../../profile/personal_access_tokens.md) with `write_repository` scope. 1. On the source GitLab instance: @@ -211,7 +212,7 @@ If it isn't working correctly, a red `error` tag appears and shows the error mes 1. Fill in the **Password** field with the GitLab personal access token created on the destination GitLab instance. 1. Select **Mirror repository**. -## Pulling from a remote repository **(PREMIUM)** +## Pull from a remote repository **(PREMIUM)** > - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. > - Moved to GitLab Premium in 13.9. @@ -224,7 +225,7 @@ to browse its content and its activity using the GitLab interface, you can confi mirror pulling: 1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) - for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) + for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the `read_repository` scope. If 2FA is enabled, this personal access token serves as your GitHub password. 1. In your project, go to **Settings > Repository**, and then expand the @@ -238,18 +239,12 @@ mirror pulling: - **Only mirror protected branches** 1. Select **Mirror repository** 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 remote repository. Changes pushed to the remote repository are pulled into the GitLab repository, either: - Automatically in a certain period of time. -- When a [forced update](#forcing-an-update) is initiated. +- When a [forced update](#force-an-update) is initiated. WARNING: If you do manually update a branch in the GitLab repository, the branch becomes diverged from @@ -273,7 +268,7 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If ### Overwrite diverged branches **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. @@ -285,7 +280,7 @@ To use this option, check the **Overwrite diverged branches** box when creating ### Trigger pipelines for mirror updates **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If this option is enabled, pipelines trigger when branches or tags are updated from the remote repository. Depending on the activity of the remote @@ -295,7 +290,7 @@ assigned when you set up pull mirroring. ### Hard failure **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure and mirroring attempts stop. This failure is visible in either the: @@ -303,11 +298,11 @@ and mirroring attempts stop. This failure is visible in either the: - Project's main dashboard. - Pull mirror settings page. -You can resume the project mirroring again by [forcing an update](#forcing-an-update). +You can resume the project mirroring again by [forcing an update](#force-an-update). ### Trigger an update using the API **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), @@ -317,18 +312,19 @@ For more information, see [Start the pull mirroring process for a Project](../.. ## Mirror only protected branches **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. Based on the mirror direction that you choose, you can opt to mirror only the -[protected branches](../protected_branches.md) from/to your remote repository. -For pull mirroring, non-protected branches are not mirrored and can diverge. +[protected branches](../protected_branches.md) in the mirroring project, +either from or to your remote repository. For pull mirroring, non-protected branches in +the mirroring project are not mirrored and can diverge. To use this option, check the **Only mirror protected branches** box when creating a repository mirror. **(PREMIUM)** ## SSH authentication -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. SSH authentication is mutual: @@ -369,7 +365,7 @@ fingerprints in the open for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/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/) @@ -417,7 +413,7 @@ NOTE: The generated keys are stored in the GitLab database, not in the file system. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. -## Forcing an update **(FREE)** +## Force an update **(FREE)** While mirrors are scheduled to update automatically, you can always force an update by using the update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. @@ -426,7 +422,7 @@ update button which is available on the **Mirroring repositories** section of th ## Bidirectional mirroring **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring may cause conflicts. @@ -450,13 +446,17 @@ protected branches. ### Configure a webhook to trigger an immediate pull to GitLab -Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you must configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. +Assuming you have already configured the [push](#set-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) +and [pull](#pull-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an +immediate pull as suggested above, you must configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) +in the downstream instance. To do this: 1. Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. 1. In your project, go to **Settings > Webhooks**. -1. Add the webhook URL which (in this case) uses the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after updates to the repository. +1. Add the webhook URL which (in this case) uses the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) + request to trigger an immediate pull after updates to the repository. ```plaintext https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> @@ -467,7 +467,7 @@ To do this: To test the integration, select the **Test** button and confirm GitLab doesn't return an error message. -### Preventing conflicts using a `pre-receive` hook +### Prevent conflicts using a pre-receive hook WARNING: The solution proposed negatively affects the performance of @@ -550,7 +550,7 @@ Note that this sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update, and Git displays warnings about it. -### Mirroring with Perforce Helix via Git Fusion **(PREMIUM)** +### Mirror with Perforce Helix via Git Fusion **(PREMIUM)** > Moved to GitLab Premium in 13.9. @@ -583,14 +583,52 @@ Should an error occur during a push, GitLab displays an **Error** highlight for ### 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. +If you receive a "13:Received RST_STREAM with error code 2" message 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. ### 4:Deadline Exceeded -When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. +When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you +may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. ### Connection blocked because server only allows public key authentication -As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a [TCP Check](../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. +As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a +[TCP Check](../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, +you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. + +### Could not read username: terminal prompts disabled + +If you receive this error after creating a new project using +[GitLab CI/CD for external repositories](../../../ci/ci_cd_for_external_repos/): + +```plaintext +"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled\n": exit status 128." +``` + +Check if the repository owner is specified in the URL of your mirrored repository: + +1. Go to your project. +1. In the left sidebar, select **Settings > Repository**. +1. Select **Mirroring repositories**. +1. If no repository owner is specified, delete and add the URL again in this format: + + ```plaintext + https://**<repo_owner>**@bitbucket.org/<accountname>/<reponame>.git + ``` + +The repository owner is needed for Bitbucket to connect to the repository for mirroring. + +### Pull mirror is missing LFS files + +In some cases, pull mirroring does not transfer LFS files. This issue occurs when: + +- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. + There is [an issue to fix this for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). +- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. + This was [fixed in GitLab 14.0.6](https://gitlab.com/gitlab-org/gitlab/-/issues/335123). +- You mirror an external repository using object storage. + There is [an issue to fix this](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index d7fbff23e5e..4ac1113152c 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -122,7 +122,7 @@ You can also sort the requirements list by: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. -GitLab supports [requirements test reports](../../../ci/yaml/README.md#artifactsreportsrequirements) now. +GitLab supports [requirements test reports](../../../ci/yaml/index.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index dd646a54b43..d46e55ca005 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -147,7 +147,7 @@ To use a custom issue template with Service Desk, in your project: 1. Go to **Settings > General > Service Desk**. 1. From the dropdown **Template to append to all Service Desk issues**, select your template. -### Using custom email display name +### Using a custom email display name > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. @@ -160,22 +160,29 @@ To edit the custom email display name: 1. Enter a new name in **Email display name**. 1. Select **Save Changes**. -### Using custom email address **(FREE SELF)** +### Using a custom email address **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. -If the `service_desk_email` is configured, then you can create Service Desk -issues by sending emails to the Service Desk email address. The default -address has the following format: -`project_contact+%{key}@example.com`. +It is possible to customize the email address used by Service Desk. To do this, you must configure +both a [custom mailbox](#configuring-a-custom-mailbox) and a +[custom suffix](#configuring-a-custom-email-address-suffix). -The `%{key}` part is used to find the project where the issue should be created. The -`%{key}` part combines the path to the project and configurable project name suffix: -`<project_full_path>-<project_name_suffix>`. +#### Configuring a custom mailbox -You can set the project name suffix in your project's Service Desk settings. -It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). +NOTE: +On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, so you only have to configure the +[custom suffix](#configuring-a-custom-email-address-suffix) in project settings. + +Using the `service_desk_email` configuration, you can customize the mailbox +used by Service Desk. This allows you to have a separate email address for +Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) +in project settings. + +The `address` must include the `+%{key}` placeholder within the 'user' +portion of the address, before the `@`. This is used to identify the project +where the issue should be created. NOTE: The `service_desk_email` and `incoming_email` configurations should @@ -183,7 +190,7 @@ always use separate mailboxes. This is important, because emails picked from `service_desk_email` mailbox are processed by a different worker and it would not recognize `incoming_email` emails. -To configure a custom email address for Service Desk with IMAP, add the following snippets to your configuration file: +To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: - Example for installations from source: @@ -207,57 +214,37 @@ To configure a custom email address for Service Desk with IMAP, add the followin ```ruby gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" - gitlab_rails['service_desk_email_email'] = "project_support@gmail.com" - gitlab_rails['service_desk_email_password'] = "[REDACTED]" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_idle_timeout'] = 60 - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_host'] = "imap.gmail.com" - gitlab_rails['service_desk_email_port'] = 993 - gitlab_rails['service_desk_email_ssl'] = true - gitlab_rails['service_desk_email_start_tls'] = false ``` -In this case, suppose the `mygroup/myproject` project Service Desk settings has the project name -suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. -As a result, a new Service Desk issue is created from this email in the `mygroup/myproject` project. - The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). -#### Microsoft Graph +##### Microsoft Graph > Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Follow the [documentation in the incoming e-mail section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). +Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). - Example for Omnibus GitLab installations: ```ruby gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" - gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_inbox_method'] = 'microsoft_graph' - gitlab_rails['service_desk_inbox_options'] = { 'tenant_id': '<YOUR-TENANT-ID>', 'client_id': '<YOUR-CLIENT-ID>', @@ -268,6 +255,22 @@ Graph API instead of IMAP. Follow the [documentation in the incoming e-mail sect The Microsoft Graph API is not yet supported in source installations. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326169) for more details. +#### Configuring a custom email address suffix + +You can set a custom suffix in your project's Service Desk settings once you have configured a [custom mailbox](#configuring-a-custom-mailbox). +It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). + +When configured, the custom suffix creates a new Service Desk email address, consisting of the +`service_desk_email_address` setting and a key of the format: `<project_full_path>-<custom_suffix>` + +For example, suppose the `mygroup/myproject` project Service Desk settings has the following configured: + +- Project name suffix is set to `support`. +- Service Desk email address is configured to `contact+%{key}@example.com`. + +The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. +The [incoming email](../../administration/incoming_email.md) address still works. + ## Using Service Desk You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 890784cecf5..d5fdb86c9b0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -110,7 +110,7 @@ and the exports between them are compatible. You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. This assumes [version history](#version-history) requirements are met. -If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../README.md). +If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../index.md). ## Exported contents @@ -156,7 +156,7 @@ To export a project and its data, follow these steps:  -1. Once the export is generated, you should receive an e-mail with a link to +1. Once the export is generated, you should receive an email with a link to download the file:  @@ -183,7 +183,7 @@ To export a project and its data, follow these steps: NOTE: If use of the `Internal` visibility level -[is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), +[is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. NOTE: diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 03a77e42765..d79d9f5b9dc 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -165,7 +165,7 @@ cannot change them: - Includes any jobs that drive the logic of your job. - Explicitly set the container image file to run the job in. This ensures that your script steps execute in the correct environment. -- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/README.md#job-keywords). +- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). This ensures that your job uses the settings you intend and that they are not overriden by project-level pipelines. @@ -188,8 +188,8 @@ Use the switches to enable or disable the following features: | **Issues** | ✓ | Activates the GitLab issues tracker | | **Repository** | ✓ | Enables [repository](../repository/) functionality | | **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../working_with_projects.md#fork-a-project) functionality | -| **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | +| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality | +| **Pipelines** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality | | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | @@ -251,7 +251,7 @@ Set up your project's merge request settings: - Enable [merge request approvals](../merge_requests/approvals/index.md). - Enable [status checks](../merge_requests/status_checks.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). +- Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). @@ -267,7 +267,8 @@ Learn how to [export a project](import_export.md#importing-the-project) in GitLa ### Advanced settings -Here you can run housekeeping, archive, rename, transfer, [remove a fork relationship](#removing-a-fork-relationship), or remove a project. +Here you can run housekeeping, archive, rename, transfer, +[remove a fork relationship](#removing-a-fork-relationship), or delete a project. #### Archiving a project @@ -363,28 +364,54 @@ namespace if needed. #### Delete a project -NOTE: -Only project Owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. +You can mark a project to be deleted. + +Prerequisite: + +- You must have at least the Owner role for a project. To delete a project: -1. Navigate to your project, and select **Settings > General > Advanced**. -1. In the "Delete project" section, click the **Delete project** button. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the "Delete project" section, select **Delete project**. 1. Confirm the action when asked to. -This action: +This action deletes a project including all associated resources (issues, merge requests, and so on). -- Deletes a project including all associated resources (issues, merge requests etc). -- From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers, - group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group - to be deleted after a delayed period. - When enabled, actual deletion happens after number of days - specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) and later, on Premium or higher tiers, +group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects in a group +to be deleted after a delayed period. +When enabled, actual deletion happens after number of days +specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). WARNING: -The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to +The default behavior of [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +#### Delete a project immediately **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. + +If you don't want to wait, you can delete a project immediately. + +Prerequisites: + +- You must have at least the Owner role for a project. +- You have [marked the project for deletion](#delete-a-project). + +To immediately delete a project marked for deletion: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the "Permanently delete project" section, select **Delete project**. +1. Confirm the action when asked to. + +Your project, its repository, and all related resources, including issues and merge requests, +are deleted. + #### Restore a project **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index d7121239610..5e045ee2455 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -8,20 +8,24 @@ type: reference, howto # Project access tokens NOTE: -Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). +Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). Self-managed Free instances should review their security and compliance policies with regards to [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) and consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. -Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP. +Project access tokens are scoped to a project and can be used to authenticate with the +[GitLab API](../../../api/index.md#personalproject-access-tokens). You can also use +project access tokens with Git to authenticate over HTTPS. If you are asked for a +username when authenticating over HTTPS, you can use any non-empty value because only +the token is needed. Project access tokens expire on the date you define, at midnight UTC. -For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/README.md#personalproject-access-tokens). +For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/index.md#personalproject-access-tokens). ## Creating a project access token @@ -29,17 +33,21 @@ For examples of how you can use a project access token to authenticate with the 1. Navigate to the project you would like to create an access token for. 1. In the **Settings** menu choose **Access Tokens**. 1. Choose a name and optional expiry date for the token. +1. Choose a role for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token). 1. Click the **Create project access token** button. 1. Save the project access token somewhere safe. Once you leave or refresh - the page, you won't be able to access it again. + the page, you don't have access to it again. ## Project bot users +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. +> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. + Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. For each project access token created, a bot user is created and added to the project with -[Maintainer level permissions](../../permissions.md#project-members-permissions). +the [specified level permissions](../../permissions.md#project-members-permissions). For the bot: diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index b7fd14ae74b..29aedb33003 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -6,16 +6,12 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Time Tracking +# Time tracking **(FREE)** -> Introduced in GitLab 8.14. +With time tracking you can track estimates and time spent on issues and merge +requests in GitLab. -Time Tracking allows you to track estimates and time spent on issues and merge -requests within GitLab. - -## Overview - -Time Tracking allows you to: +Use time tracking for these tasks: - 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 @@ -24,14 +20,13 @@ Time Tracking allows you to: 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. +Data about time tracking shows up on the issue and merge request sidebar:  ## How to enter data -Time Tracking uses two [quick actions](quick_actions.md): `/spend` and `/estimate`. +Time tracking uses two [quick actions](quick_actions.md): `/spend` and `/estimate`. If you use either quick action more than once in a single comment, only the last occurrence is applied. @@ -44,9 +39,10 @@ with [Reporter and higher permission levels](../permissions.md). ### Estimates -To enter an estimate, write `/estimate`, followed by the time. For example, if -you need to enter an estimate of 1 month, 2 weeks, 3 days, 4 hours and 5 minutes, -write `/estimate 1mo 2w 3d 4h 5m`. +To enter an estimate, type `/estimate`, followed by the time. + +For example, if you need to enter an estimate of 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, +type `/estimate 1mo 2w 3d 4h 5m`. Check the [time units you can use](#configuration). Every time you enter a new time estimate, any previous time estimates are @@ -57,21 +53,22 @@ To remove an estimation entirely, use `/remove_estimate`. ### Time spent -To enter time spent, write `/spend`, followed by the time. For example, if you need -to log 1 month, 2 weeks, 3 days, 4 hours and 5 minutes, you would write `/spend 1mo 2w 3d 4h 5m`. -Time units that we support are listed at the bottom of this help page. +To enter time spent, type `/spend`, followed by the time. + +For example, if you need +to log 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/spend 1mo 2w 3d 4h 5m`. +Check the [time units you can use](#configuration). Every new time spent entry is added to the current total time spent for the issue or the merge request. -You can remove time by entering a negative amount: for example, `/spend -3d` removes three +To subtract time, enter a negative value. For example, `/spend -3d` removes three days from the total time spent. You can't go below 0 minutes of time spent, -so GitLab automatically resets the time spent if you remove a larger amount -of time compared to the time that was entered already. +so if you remove more time than already entered, GitLab ignores the subtraction. You can log time in the past by providing a date after the time. For example, if you want to log 1 hour of time spent on the 31 January 2021, -you would write `/spend 1h 2021-01-31`. If you supply a date in the future, the +you would type `/spend 1h 2021-01-31`. If you supply a date in the future, the command fails and no time is logged. To remove all the time spent at once, use `/remove_time_spent`. @@ -97,13 +94,13 @@ The breakdown of spent time is limited to a maximum of 100 entries. 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. +| Time unit | What to type | Default conversion rate | +| --------- | ------------ | ----------------------- | +| Month | `mo` | 4w | +| Week | `w` | 5d | +| Day | `d` | 8h | +| Hour | `h` | 60m | +| Minute | `m` | | ### Limit displayed units to hours **(FREE SELF)** @@ -121,11 +118,11 @@ To do so: With this option enabled, `75h` is displayed instead of `1w 4d 3h`. -## Other interesting links +## Related links -- [Time Tracking solutions page](https://about.gitlab.com/solutions/time-tracking/) -- Time Tracking GraphQL references: +- [Time tracking solutions page](https://about.gitlab.com/solutions/time-tracking/) +- Time tracking GraphQL references: - [Connection](../../api/graphql/reference/index.md#timelogconnection) - [Edge](../../api/graphql/reference/index.md#timelogedge) - [Fields](../../api/graphql/reference/index.md#timelog) - - [Group Timelogs](../../api/graphql/reference/index.md#grouptimelogs) + - [Group timelogs](../../api/graphql/reference/index.md#grouptimelogs) diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 0e597725611..722505304c0 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -331,7 +331,7 @@ The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernete In order to enable the Web IDE terminals you need to create the file `.gitlab/.gitlab-webide.yml` inside the repository's root. This -file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) +file is fairly similar to the [CI configuration file](../../../ci/yaml/index.md) syntax but with some restrictions: - No global blocks (such as `before_script` or `after_script`) can be defined. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index ed6a51665bd..527db38c980 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -44,7 +44,7 @@ users see when viewing the wiki: ## Create a new wiki page -Users with Developer [permissions](../../permissions.md) can create new wiki pages: +Users with the [Developer role](../../permissions.md) can create new wiki pages: 1. Go to your project or group and select **Wiki**. 1. Select **New page** on this page, or any other wiki page. @@ -108,7 +108,7 @@ may not be able to check out the wiki locally afterward. ## Edit a wiki page -You need Developer [permissions](../../permissions.md) or higher to edit a wiki page: +You need the [Developer role](../../permissions.md) or higher to edit a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to edit. @@ -133,7 +133,7 @@ You need the [Maintainer role](../../permissions.md) or higher to delete a wiki ## Move a wiki page -You need Developer [permissions](../../permissions.md) or higher to move a wiki page: +You need the [Developer role](../../permissions.md) or higher to move a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to move. @@ -234,7 +234,7 @@ wikis, with a few limitations: For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). -Group wikis can be edited by members with [Developer permissions](../../permissions.md#group-members-permissions) +Group wikis can be edited by members with the [Developer role](../../permissions.md#group-members-permissions) and above. Group wiki repositories can be moved using the [Group repository storage moves API](../../../api/group_repository_storage_moves.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index a0b20f5c86d..08b63bfed5f 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -14,12 +14,17 @@ code are saved in projects, and most features are in the scope of projects. You can explore other popular projects available on GitLab. To explore projects: 1. On the top bar, select **Menu > Project**. -1. Select **Explore Projects**. +1. Select **Explore projects**. GitLab displays a list of projects, sorted by last updated date. To view projects with the most [stars](#star-a-project), click **Most stars**. To view projects with the largest number of comments in the past month, click **Trending**. +NOTE: +By default, `/explore` is visible to unauthenticated users. However, if the +[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restricted-visibility-levels) +is restricted, `/explore` is visible only to signed-in users. + ## Create a project To create a project in GitLab: @@ -84,7 +89,7 @@ Built-in templates are project templates that are: - Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups. - Released with GitLab. -- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates). +- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). To use a built-in template on the **New project** page: @@ -148,7 +153,7 @@ and then [cloning the repository](../../gitlab-basics/start-using-git.md#clone-a locally, you can directly push it to GitLab to create the new project, all without leaving your terminal. If you have access rights to the associated namespace, GitLab automatically creates a new project under that GitLab namespace with its visibility -set to Private by default (you can later change it in the [project's settings](../../public_access/public_access.md#how-to-change-project-visibility)). +set to Private by default (you can later change it in the [project's settings](../../public_access/public_access.md#change-project-visibility)). This can be done by using either SSH or HTTPS: |
