diff options
Diffstat (limited to 'doc/user/project')
152 files changed, 2354 insertions, 1353 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 6994f16cf52..542a3763008 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,6 +1,6 @@ # Badges -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41174) in GitLab 10.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. Badges are a unified way to present condensed pieces of information about your projects. They consist of a small image and additionally a URL that the image diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index f4733620640..6d091c431a2 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,32 +1,60 @@ -# Bulk editing issues and merge requests +--- +stage: Plan +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/#designated-technical-writers +--- -> **Notes:** -> -> - A permission level of `Reporter` or higher is required in order to manage -> issues. -> - A permission level of `Developer` or higher is required in order to manage -> merge requests. +# Bulk editing issues and merge requests at the project level -Attributes can be updated simultaneously across multiple issues or merge requests -by using the bulk editing feature. +NOTE: **Note:** +Bulk editing issues, epics, and merge requests is also available at the **group level**. +For more details, see +[Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). + +If you want to update attributes across multiple issues or merge requests, you can do it +by bulk editing them, that is, editing them together.  +## Bulk edit issues at the project level + NOTE: **Note:** -Bulk editing issues and merge requests is also available at the group level. -For more details, see [bulk editing group issues and merge requests](../group/bulk_editing/index.md). +You need a permission level of [Reporter or higher](../permissions.md) to manage issues. + +When bulk editing issues in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions -To update multiple project issues or merge requests at the same time: +To update multiple project issues at the same time: -1. Navigate to their respective list. +1. In a project, go to **{issues}** **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the project level + +NOTE: **Note:** +You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. -1. Click **Edit issues** or **Edit merge requests**. +When bulk editing merge requests in a project, you can edit the following attributes: - - This will open a sidebar on the right-hand side of your screen - where editable fields will be displayed. +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions - - Checkboxes will also appear beside each issue or merge request. +To update multiple project merge requests at the same time: -1. Check the checkboxes of each items to be edited. -1. Choose the appropriate fields and their values from the sidebar. +1. In a project, go to **{merge-request}** **Merge Requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. 1. Click **Update all**. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 86e9df1d162..852baf1f628 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,6 +1,6 @@ # Canary Deployments **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 712f8ea0adc..b11483a7446 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -51,7 +51,7 @@ Generate an access key for the IAM user, and configure GitLab with the credentia ## New EKS cluster -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5. +> [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: @@ -147,7 +147,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. + in your VPC where your worker nodes will 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. @@ -164,114 +164,45 @@ You will need to add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. +### Troubleshooting creating a new cluster + +The following errors are commonly encountered when creating a new cluster. + +#### Error: Request failed with status code 422 + +When submitting the initial authentication form, GitLab returns a status code 422 +error when it can't determine the role you've provided. Make sure you've +correctly configured your role with the **Account ID** and **External ID** +provided by GitLab. In GitLab, make sure to enter the correct **Role ARN**. + +#### 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 +insufficient permissions to retrieve the resources needed for the form. Make sure +you've assigned the role the correct permissions. + +#### `ROLLBACK_FAILED` during cluster creation + +The creation process halted because GitLab encountered an error when creating +one or more resources. You can inspect the associated +[CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-view-stack-data-resources.html) +to find the specific resources that failed to create. + +If the `Cluster` resource failed with the error +`The provided role doesn't have the Amazon EKS Managed Policies associated with it.`, +the role specified in **Role name** is not configured correctly. + +NOTE: **Note:** +This role should not be the same as the one created above. If you don't have an +existing +[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html), +you must create one. + ## Existing EKS cluster -To add an existing EKS cluster to your project, group, or instance: - -1. Perform the following steps on the EKS cluster: - 1. Retrieve the certificate. A valid Kubernetes certificate is needed to authenticate to the - EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: - - 1. List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - 1. Get the certificate with: - - ```shell - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - 1. Create admin token. A `cluster-admin` token is required to install and manage Helm Tiller. - GitLab establishes mutual SSL authentication with Helm Tiller and creates limited service - accounts for each application. To create the token we will create an admin service account as - follows: - - 1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the service account to your cluster: - - ```shell - $ kubectl apply -f eks-admin-service-account.yaml - serviceaccount "eks-admin" created - ``` - - 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the cluster role binding to your cluster: - - ```shell - $ kubectl apply -f eks-admin-cluster-role-binding.yaml - clusterrolebinding "eks-admin" created - ``` - - 1. Retrieve the token for the `eks-admin` service account: - - ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - 1. Locate the API server endpoint so GitLab can connect to the cluster. This is displayed on - the AWS EKS console, when viewing the EKS cluster details. -1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **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: - - **Kubernetes cluster name**: A name for the cluster to identify it within GitLab. - - **Environment scope**: Leave this as `*` for now, since we are only connecting a single cluster. - - **API URL**: The API server endpoint retrieved earlier. - - **CA Certificate**: The certificate data from the earlier step, as-is. - - **Service Token**: The admin token value. - - For project-level clusters, **Project namespace prefix**: This can be left blank to accept the - default namespace, based on the project name. -1. Click on **Add Kubernetes cluster**. The cluster is now connected to GitLab. - -At this point, [Kubernetes deployment variables](index.md#deployment-variables) will -automatically be available during CI/CD jobs, making it easy to interact with the cluster. - -If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. +For information on adding an existing EKS cluster, see +[Existing Kubernetes cluster](add_remove_clusters.md#existing-kubernetes-cluster). ### Create a default Storage Class diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 4094828323a..2746076befe 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -21,26 +21,25 @@ requirements are met: ## New GKE cluster -Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters +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). -### Important notes - Note the following: - The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab at the instance level. If that's not the case, ask your GitLab administrator to enable it. On GitLab.com, this is enabled. -- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters +- 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 more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR notation. - 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). Starting from [GitLab - 11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will - explicitly request that basic authentication and client certificate is enabled. + set up an [initial service account](add_remove_clusters.md#access-controls). 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. ### Creating the cluster on GKE diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index fddc9873f17..d0cba729e35 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -50,7 +50,7 @@ a `gitlab` service account with `cluster-admin` privileges is created in the `de to manage the newly created cluster. NOTE: **Note:** -Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) in GitLab 11.5. +Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. When you install Helm into your cluster, the `tiller` service account is created with `cluster-admin` privileges in the `gitlab-managed-apps` @@ -151,146 +151,142 @@ For more information, see information for adding an: NOTE: **Note:** Kubernetes integration is not supported for arm64 clusters. See the issue -[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. +[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64044) for details. ### Existing Kubernetes cluster To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + 1. Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. + 1. **{admin}** **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: - - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required) - The - [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. - - **API URL** (required) - - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes - exposes several APIs, we want the "base" URL that is common to all of them. - 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 'Kubernetes master' | awk '/http/ {print $NF}' - ``` - - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should be named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: - - ```shell - - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - - ``` - - NOTE: **Note:** - If the command returns the entire certificate chain, you need copy the *root ca* - certificate at the bottom of the chain. - - - **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. - **The token used should belong to a service account with - [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges.** To create this service account: - - 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```shell - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - You will need the `container.clusterRoleBindings.create` permission - to create cluster-level roles. If you do not have this permission, - you can alternatively enable Basic Authentication and then run the - `kubectl apply` command as an admin: - - ```shell - kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> - ``` - - NOTE: **Note:** - Basic Authentication can be turned on and the password credentials - can be obtained using the Google Cloud Console. - - Output: - - ```shell - serviceaccount "gitlab-admin" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab-admin` service account: - - ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin + 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-premium) 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 'Kubernetes master' | awk '/http/ {print $NF}' + ``` + + 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will 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 + ``` + + NOTE: **Note:** + If the command returns the entire certificate chain, you need copy the *root ca* + certificate at the bottom of the chain. + + 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-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```shell + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + You will need the `container.clusterRoleBindings.create` permission + to create cluster-level roles. If you do not have this permission, + you can alternatively enable Basic Authentication and then run the + `kubectl apply` command as an admin: + + ```shell + kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> + ``` + + NOTE: **Note:** + Basic Authentication can be turned on and the password credentials + can be obtained using the Google Cloud Console. + + Output: + + ```shell + serviceaccount "gitlab-admin" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab-admin` service account: + + ```shell + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - NOTE: **Note:** - For GKE clusters, you will need the - `container.clusterRoleBindings.create` permission to create a cluster - role binding. You can follow the [Google Cloud - documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) - to grant access. - - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. - See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. - - - **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab will create one for you. Also: - - Each project should have a unique namespace. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + role binding. You can follow the [Google Cloud + documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. + + 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 will create one for you. Also: + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. 1. Finally, click the **Create Kubernetes cluster** button. @@ -337,7 +333,7 @@ To disable the Kubernetes cluster integration, follow the same procedure. To remove the Kubernetes cluster integration from your project, either: - Select **Remove integration**, to remove only the Kubernetes integration. -- [From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/26815), select +- [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. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 1298a24fcac..961a9fda5ff 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes clusters -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/35954) in GitLab 10.1 for projects. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/34758) in +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in > GitLab 11.6 for [groups](../../group/clusters/index.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/39840) in +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in > GitLab 11.11 for [instances](../../instance/clusters/index.md). GitLab provides many features with a Kubernetes integration. Kubernetes can be @@ -46,6 +46,7 @@ GitLab is committed to support at least two production-ready Kubernetes minor ve Currently, GitLab supports the following Kubernetes versions: +- 1.16 - 1.15 - 1.14 - 1.13 (deprecated, support ends on November 22, 2020) @@ -171,7 +172,7 @@ Note the following with GitLab and clusters: #### Clearing the cluster cache -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31759) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you @@ -314,7 +315,7 @@ If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be ### Custom namespace -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. The Kubernetes integration defaults to project-environment-specific namespaces of the form `<project_name>-<project_id>-<environment>` (see [Deployment @@ -326,7 +327,7 @@ in `.gitlab-ci.yml`. NOTE: **Note:** When using a [GitLab-managed cluster](#gitlab-managed-clusters), the namespaces are created automatically prior to deployment and [can not be -customized](https://gitlab.com/gitlab-org/gitlab/issues/38054). +customized](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). ### Troubleshooting diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 8577231b69b..509be4ed0a8 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes Logs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). @@ -65,23 +65,23 @@ Logs can be displayed by clicking on a specific pod from [Deploy Boards](../depl The **Log Explorer** lets you filter the logs by: - Pods. -- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. +- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/5769), environments. - [From GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656), [full text search](#full-text-search). -- [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/197879), dates. +- [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/197879), dates. Loading more than 500 log lines is possible from [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198050) onward. Support for pods with multiple containers is coming -[in a future release](https://gitlab.com/gitlab-org/gitlab/issues/13404). +[in a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/13404). Support for historical data is coming -[in a future release](https://gitlab.com/gitlab-org/gitlab/issues/196191). +[in a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/196191). ### Filter by date -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197879) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197879) in GitLab 12.8. When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, you can filter logs displayed in the **Log Explorer** by date. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index dfed43470bc..92ef35ad93f 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -23,7 +23,7 @@ pre-written code blocks or database queries against a given environment. ## Executable Runbooks -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/45912) in GitLab 11.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45912) in GitLab 11.4. The JupyterHub app offered via GitLab’s Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 124a0d4bf9f..15f7e14fda9 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -15,7 +15,7 @@ GitLab supports deployment of AWS Lambda functions through GitLab CI/CD using th ## Serverless Framework -The [Serverless Framework can deploy to AWS](https://serverless.com/framework/docs/providers/aws/). +The [Serverless Framework can deploy to AWS](https://www.serverless.com/framework/docs/providers/aws/). We have prepared an example with a step-by-step guide to create a simple function and deploy it on AWS. @@ -101,7 +101,7 @@ The handler definition will provision the Lambda function using the source code The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. -You can read more about the available properties and additional configuration possibilities of the Serverless Framework here: <https://serverless.com/framework/docs/providers/aws/guide/serverless.yml/> +You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. #### Crafting the `.gitlab-ci.yml` file @@ -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: <https://docs.gitlab.com/ee/ci/variables/README.html#via-the-ui> +For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). NOTE: **Note:** The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. @@ -275,7 +275,7 @@ module.exports.hello = async event => { }; ``` -For more information, see the [Your CORS and API Gateway survival guide](https://serverless.com/blog/cors-api-gateway-survival-guide/) +For more information, see the [Your CORS and API Gateway survival guide](https://www.serverless.com/blog/cors-api-gateway-survival-guide/) blog post written by the Serverless Framework team. #### Writing automated tests @@ -288,7 +288,7 @@ automated testing of both local and deployed serverless function. The example code is available: -- As a [cloneable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). +- As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). You can also use a [template](../../../../gitlab-basics/create-project.md#project-templates) @@ -416,7 +416,7 @@ production: environment: production ``` -Let’s examine the config file more closely: +Let’s examine the configuration file more closely: - `image` specifies the Docker image to use for this build. This is the latest Python image since the sample application is written in Python. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 2156d96f92a..45fb313d177 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -33,7 +33,7 @@ of the box through its main components: - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. - [Eventing](https://github.com/knative/eventing): Management and delivery of events. -For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs). +For more information on Knative, visit the [Knative docs repository](https://github.com/knative/docs). With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. @@ -61,14 +61,14 @@ To run Knative on GitLab, you will need: wildcard domain where your applications will be served. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) + to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file will contain the information for all the functions being hosted in the repository as well as a reference to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your - project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions + project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. See [Installing Applications](../index.md#installing-applications) for more information. @@ -97,9 +97,9 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. 1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` - pointing the ip address or hostname of the Ingress. + pointing the IP address or hostname of the Ingress. -  +  NOTE: **Note:** You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) @@ -107,7 +107,7 @@ on a given project but not both. The current implementation makes use of a `serv ## Using an existing installation of Knative -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/58941) in GitLab 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. NOTE: **Note:** The "invocations" monitoring feature of GitLab serverless will not work when @@ -199,7 +199,7 @@ You must provide a `Dockerfile` to run serverless functions if no runtime is spe ### OpenFaaS runtimes -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29253) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29253) in GitLab 12.5. [OpenFaaS classic runtimes](https://github.com/openfaas/templates#templates-in-store) can be used with GitLab serverless. @@ -318,7 +318,7 @@ Explanation of the fields used above: |-----------|-------------| | `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh middleware. | | `envs` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are the variable contents. You may replace this with your own variables. | -| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for **all** functions in the file. The secrets are expected in ini format. | +| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for **all** functions in the file. The secrets are expected in INI format. | ### `functions` @@ -332,7 +332,7 @@ subsequent lines contain the function attributes. | `runtime` (optional)| The runtime to be used to execute the function. This can be a runtime alias (see [Runtime aliases](#runtime-aliases)), or it can be a full URL to a custom runtime repository. When the runtime is not specified, we assume that `Dockerfile` is present in the function directory specified by `source`. | | `description` | A short description of the function. | | `envs` | Sets an environment variable for the specific function only. | -| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for the specific function only. The secrets are expected in ini format. | +| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for the specific function only. The secrets are expected in INI format. | ### Deployment @@ -384,7 +384,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO http://functions-echo.functions-1.functions.example.com/ ``` - 1. Using a web-based tool (ie. postman, restlet, etc) + 1. Using a web-based tool (such as Postman or Restlet)  @@ -516,7 +516,7 @@ cluster. ## Configuring logging -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33330) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33330) in GitLab 12.5. ### Prerequisites diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 40ea1833fa3..6b81aea4b87 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -6,8 +6,8 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/issues/53182) added in GitLab Starter 12.1. -> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. +> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) added in GitLab Starter 12.1. +> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. ## Introduction @@ -73,12 +73,28 @@ be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)** +NOTE: **Note**: +Developer or higher [permissions](../permissions.md) are required in order to +approve a merge request. + Once set, Code Owners are displayed in merge requests widgets:  -NOTE: **Note**: - While the`CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules) it can also be used as the sole driver of a Merge Request approval (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)) by simply creating the file in one of the three locations specified above, configuring the Code Owners to be required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium) and then using [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) to specify the actual owners and granular permissions. +While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules) +it can also be used as the sole driver of merge request approvals +(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). +To do so, create the file in one of the three locations specified above and +set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). +Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) +to specify the actual owners and granular permissions. + +Using Code Owners in conjunction with [Protected Branches Approvals](protected_branches.md#protected-branches-approval-by-code-owners-premium) +will prevent any user who is not specified in the `CODEOWNERS` file from pushing changes +for the specified files/paths, even if their role is included in the **Allowed to push** column. +This allows for a more inclusive push strategy, as administrators don't have to restrict developers +from pushing directly to the protected branch, but can restrict pushing to certain +files where a review by Code Owners is required. ## The syntax of Code Owners files @@ -93,7 +109,7 @@ groups or subgroups from the project's group hierarchy as potential code owners. For example, consider the following hierarchy for a given project: -```text +```plaintext group >> sub-group >> sub-subgroup >> myproject >> file.md ``` @@ -103,7 +119,7 @@ Any of the following groups would be eligible to be specified as code owners: - `@group/sub-group` - `@group/sub-group/sub-subgroup` -In addition, any groups that have been invited to the project using the **Settings > Members** tool will also be recognized as eligible code owners. +In addition, any groups that have been invited to the project using the **Members** tool will also be recognized as eligible code owners. The order in which the paths are defined is significant: the last pattern that matches a given path will be used to find the code diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8f7bb844e37..0a613ff918b 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,6 +1,13 @@ +--- +stage: Release +group: Progressive Delivery +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto, reference +--- + # Deploy Boards **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. GitLab's Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -34,6 +41,10 @@ knowledge. In particular, you should be familiar with: - [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) +NOTE: **Note:** +Apps that consist of multiple deployments are shown as duplicates on the deploy board. +Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) for details. + ## Use cases Since the Deploy Board is a visual representation of the Kubernetes pods for a @@ -68,7 +79,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) - and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/issues/4584). + 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 [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. diff --git a/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png b/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png Binary files differnew file mode 100644 index 00000000000..462141ef82a --- /dev/null +++ b/doc/user/project/deploy_keys/img/deploy_keys_v13_0.png diff --git a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png b/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png Binary files differnew file mode 100644 index 00000000000..3e6d1605f95 --- /dev/null +++ b/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md new file mode 100644 index 00000000000..32d3eab5e62 --- /dev/null +++ b/doc/user/project/deploy_keys/index.md @@ -0,0 +1,164 @@ +--- +stage: Release +group: Progressive Delivery +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto, reference +--- + +# Deploy Keys + +Deploy keys allow read-only or read-write (if enabled) access to one or +more repositories, by importing an SSH public key to your GitLab instance. + +This is useful for cloning repositories to your Continuous +Integration (CI) server. By using deploy keys, you don't have to set up a +dummy user account. + +There are two types of deploy keys: + +- [Project deploy keys](#project-deploy-keys) +- [Public deploy keys](#public-deploy-keys) + +## Key details on deploy keys + +Deploy Keys allow a remote machine (VM, physical, and so on) to access a GitLab +repository with just a few steps. If you want a remote machine to interact with a GitLab +repository in automation, it's a simple solution. + +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 access only to trusted users, +and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) +in the GitLab project. + +If this security implication is a concern for your organization, +[Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more +security control. + +## Deploy Keys Permissions + +You can choose the access level of a deploy key when you enable it on a project: + +- `read-only`: The deploy key can read a repository. +- `read-write`: The deploy key can read a repository and write to it. + +Project maintainers and owners can activate and deactivate deploy keys. +They can also add their own deploy keys and enable them for this project. + +When a `write-access` deploy key is used to push a commit, GitLab checks if +the **creator** of the deploy key has permission to access the resource. For example: + +- When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), + the **creator** of the deploy key must have access to the branch. +- When a deploy key is used to push a commit that triggers a CI/CD pipelines, the **creator** of + the deploy key must have access to the CI/CD resources (like protected environments, secret variables, and so on). +- If the **creator** of a deploy key does not have permissions to read a project's + repository, the deploy key _might_ encounter an error during the process. + +## Differences between deploy keys and deploy tokens + +Both deploy keys and [deploy tokens](../deploy_tokens/index.md#deploy-tokens) can +help you access a repository, but there are some notables differences between them: + +- Deploy keys are shareable between projects that are not related or don't even + belong to the same group. Deploy tokens belong to either a project or + [a group](../deploy_tokens/index.md#group-deploy-token). +- A deploy key is an SSH key you need to generate yourself on your machine. A deploy + token is generated by your GitLab instance, and is provided to users only once + (at creation time). +- A deploy key is valid as long as it's registered and enabled. Deploy tokens can + be time-sensitive, as you can control their validity by setting an expiration date to them. +- You can't log in to a registry with deploy keys, or perform read / write operations + on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). +- You need an SSH key pair to use deploy keys, but not deploy tokens. + +## How to enable Deploy Keys + +### Project deploy keys + +[Project maintainers and owners](../../permissions.md#project-members-permissions) +can add or enable a deploy key for a project repository: + +1. Navigate to the project's **Settings > Repository** page. +1. Expand the **Deploy Keys** section. +1. Specify a title for the new deploy key and paste your public SSH key. +1. (Optional) Check **Write access allowed** to allow `read-write` access. Leave it unchecked for `read-only` access. + +There are three lists of Project Deploy Keys: + +- Enabled deploy keys +- Privately accessible deploy keys +- Public accessible deploy keys + + + +After you add a key, it will be enabled for this project by default, and it'll appear +in the **Enabled deploy keys** tab. + +In the **Privately accessible deploy keys** tab, you can enable a private key which +has been already imported in a different project. If you have access to these keys, +it's because you have either: + +- Previously uploaded the keys yourself in a different project. +- You are a maintainer or owner of the other project where the keys were imported. + +In the **Publicly accessible deploy keys** tab, you can enable +keys that were [made available to your entire GitLab instance](#public-deploy-keys). + +After a key is added, you can edit it to update its title, or switch between `read-only` +and `read-write` access. + +NOTE: **Note:** +If you have enabled a privately or publicly accessible or deploy key for your +project, and if you then update the access level for this key from `read-only` to +`read-write`, the change will be only for the **current project**. + +### Public deploy keys + +Public deploy keys allow `read-only` or `read-write` +access to any repository in your GitLab instance. This is useful for integrating +repositories to secure, shared services, such as CI/CD. + +Instance administrators can add public deploy keys: + +1. Go to **Admin Area** (**{admin}**) **> Deploy Keys**. +1. Click on **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, + if the key gives access to a SaaS CI/CD instance, use the name of that service + in the key name if that is all the key is used for. + + + +After adding a key, it will be available to any shared systems. Project maintainers +or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. + +NOTE: **Note:** +The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears +if there is at least one Public deploy key configured. + +Public deploy keys can provide greater security compared to project deploy keys, as +the administrator of the target integrated system is the only one who needs to know the key value, +or configure it. + +When creating a Public deploy key, determine whether or not it can be defined for +very narrow usage, such as just a specific service, or if it needs to be defined for +broader usage, such as full `read-write` access for all services. + +CAUTION: **Warning:** +Adding a public deploy key does not immediately expose any repository to it. Public +deploy keys enable access from other systems, but access is not given to any project +until a project maintainer chooses to make use of it. + +## Troubleshooting + +### Deploy Key cannot push to a protected branch + +If the owner of this deploy key does not have access to a [protected +branch](../protected_branches.md), then this deploy key won't have access to +the branch either. In addition to this, choosing the **No one** value in +[the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) +means that no users **and** no services using deploy keys can push to that selected branch. + +Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 2d42debed68..10f0281d0eb 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,14 @@ +--- +stage: Release +group: Progressive Delivery +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto +--- + # Deploy Tokens > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/199370) from **Settings > Repository** in GitLab 12.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) from **Settings > CI / CD** in GitLab 13.0. @@ -120,7 +127,7 @@ To upload packages in the GitLab package registry, you'll need to: ### Group Deploy Token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/21765) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21765) in GitLab 12.9. A deploy token created at the group level can be used across all projects that belong either to the specific group or to one of its subgroups. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 16ac53a2b52..0f90c321a14 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Description templates >[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. @@ -29,7 +35,7 @@ templates of the default branch will be taken into account. For example, if you have a project for tracking new blog posts, you can require the title, outlines, author name, author social media information, and so on. - Following the previous example, you can make a template for every MR submitted - with a new blog post, requiring information about the post date, frontmatter data, + with a new blog post, requiring information about the post date, front matter data, images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. diff --git a/doc/user/project/img/status_page_detail_link_v13_1.png b/doc/user/project/img/status_page_detail_link_v13_1.png Binary files differnew file mode 100644 index 00000000000..f3d1005447c --- /dev/null +++ b/doc/user/project/img/status_page_detail_link_v13_1.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56717858b53..56266718d12 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import your project from Bitbucket Cloud to GitLab NOTE: **Note:** diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 55df2d7294d..f0e730564d8 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import your project from Bitbucket Server to GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 89a9f7da852..173ba71b167 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migrating from ClearCase [ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 3b2404912f7..d2e79458526 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migrating from CVS [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 13409c93929..149b5d1913c 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import your project from FogBugz to GitLab It only takes a few simple steps to import your project from FogBugz. diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index cf9ac15f5ac..0d6e059f1cf 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Gemnasium **(ULTIMATE)** This guide describes how to migrate from Gemnasium.com to your own GitLab diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 94ab9d9195b..543fffd33d6 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import your project from Gitea to GitLab Import your projects from Gitea to GitLab with minimal effort. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 4c213f21920..b7754e60837 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import your project from GitHub to GitLab Using the importer, you can import your GitHub repositories to GitLab.com or to diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 2f87f257754..b9aea629e85 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Project importing from GitLab.com to your private GitLab instance You can import your existing GitLab.com projects to your GitLab instance, but keep in diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a0da68eb513..86b671c8371 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migrating projects to a GitLab instance 1. [From Bitbucket Cloud](bitbucket.md) @@ -47,6 +54,10 @@ Keep in mind the limitations of the [import/export feature](../settings/import_e You will still need to migrate your Container Registry over a series of Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts. +## Migrating from GitLab.com to self-managed GitLab + +The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an admin through the UI or the [users API](../../../api/users.md#user-creation). + ## Migrating between two self-managed GitLab instances The best method for migrating from one GitLab instance to another, diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index db48282a8f3..0b8807bb9b3 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Import your Jira project issues to GitLab > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2766) in GitLab 12.10. @@ -43,6 +49,7 @@ Importing large projects may take several minutes depending on the size of the i 1. On the **{issues}** **Issues** page, click the **Import Issues** (**{import}**) button. 1. Select **Import from Jira**. + This option is only visible if you have the [correct permissions](#permissions).  diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 86c8b276887..0374e0acf9a 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -1,6 +1,13 @@ +--- +type: howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import multiple repositories by uploading a manifest file -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28811) in GitLab 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index cbcef7a2fb0..dbc1c491493 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -1,3 +1,10 @@ +--- +type: howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migrating from Perforce Helix [Perforce Helix](https://www.perforce.com/) provides a set of tools which also diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index c81d489f12b..a19068199db 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -1,6 +1,13 @@ +--- +type: howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import Phabricator tasks into a GitLab project -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/60562) in GitLab 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index c20b1cb7f5e..9b5e43aae79 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -1,3 +1,10 @@ +--- +type: howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Import project from repo by URL You can import your existing repositories by providing the Git URL: diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index cf034aafca9..d5f4a014705 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -1,3 +1,10 @@ +--- +type: howto +stage: Manage +group: Import +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Migrating from SVN to GitLab Subversion (SVN) is a central version control system (VCS) while @@ -75,7 +82,7 @@ For more information regarding the SubGit configuration options, refer to ### Initial translation -Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the +Now that SubGit has configured the Git/SVN repositories, run `subgit` to perform the initial translation of existing SVN revisions into the Git repository: ```shell @@ -159,7 +166,7 @@ svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt ``` If your SVN repository requires a username and password add the -`--username <username>` and `--password <password` flags to the above command. +`--username <username>` and `--password <password>` flags to the above command. `svn2git` also supports excluding certain file paths, branches, tags, etc. See [svn2git documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of the available options. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 9b148224e10..1c9ee7476bd 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -6,7 +6,7 @@ type: concepts Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes -[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/overview?view=azure-devops) +[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/what-is-tfvc?view=azure-devops) (TFVC), a centralized version control system similar to Git. In this document, we focus on the TFVC to Git migration. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 50272f0e007..3a4e240fb6c 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -100,7 +100,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. **(PREMIUM)** - [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. **(PREMIUM)** - [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** -- [License Compliance](../compliance/license_compliance/index.md): approve and blacklist licenses for projects. **(ULTIMATE)** +- [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** - [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)** - [Static Site Editor](static_site_editor/index.md): quickly edit content on static websites without prior knowledge of the codebase or Git commands. @@ -144,6 +144,17 @@ To view your starred projects: - Number of open merge requests - Number of open issues +### Explore projects + +You can explore other popular projects available on GitLab. To explore projects: + +1. Click **Projects** in the navigation bar. +1. Click **Explore Projects**. + +GitLab displays a list of projects, sorted by last updated date. To view +projects with the most [stars](#star-a-project), click **Most stars**. To view +projects with the largest number of comments in the past month, click **Trending**. + ## Project settings Set the project's visibility level and the access levels to its various pages @@ -250,14 +261,14 @@ password <personal_access_token> ## Access project page with project ID -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53671) in GitLab 11.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. To quickly access a project from the GitLab UI using the project ID, visit the `/projects/:id` URL in your browser or other tool accessing the project. ## Project aliases **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. When migrating repositories to GitLab and they are being accessed by other systems, it's very useful to be able to access them using the same name especially when diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 52fcad8dd80..3cc76beb323 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -273,7 +273,7 @@ you defined. ### `projects` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10904) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. You can limit where the "issuables" can be queried from: diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index db8f24fc1e1..7b21c590c8a 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -22,7 +22,7 @@ need to be configured in a Bamboo build plan before GitLab can integrate. 1. Choose 'Repository triggers the build when changes are committed' 1. Check one or more repositories checkboxes 1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a - whitelist of IP addresses that are allowed to trigger Bamboo builds. + list of IP addresses that are allowed to trigger Bamboo builds. 1. Save the trigger. 1. In the left pane, select a build stage. If you have multiple build stages you want to select the last stage that contains the Git checkout task. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 848e89c18cb..4eaf3a0d4b4 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,25 +1,34 @@ -# Custom Issue Tracker Service +# Custom Issue Tracker service -To enable the Custom Issue Tracker integration in a project, navigate to the -[Integrations page](overview.md#accessing-integrations), click -the **Customer Issue Tracker** service, and fill in the required details on the page as described -in the table below. You will be able to edit the title and description later as well. +To enable the Custom Issue Tracker integration in a project: -| Field | Description | -| ----- | ----------- | -| `title` | A title for the issue tracker (to differentiate between instances, for example). | -| `description` | A name for the issue tracker (to differentiate between instances, for example) | -| `project_url` | The URL to the project in the custom issue tracker. | -| `issues_url` | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | -| `new_issue_url` | Currently unused. Will be changed in a future release. | +1. Go to **{settings}** **Settings > Integrations**. +1. Click **Custom Issue Tracker** +1. Fill in the tracker's details, such as title, description, and URLs. + You will be able to edit these fields later as well. -Once you have configured and enabled Custom Issue Tracker Service you'll see a link on the GitLab project pages that takes you to that custom issue tracker. + These are some of the required fields: + + | Field | Description | + | --------------- | ----------- | + | **Title** | A title for the issue tracker (for example, to differentiate between instances). | + | **Description** | A name for the issue tracker (for example, to differentiate between instances). | + | **Project URL** | The URL to the project in the custom issue tracker. | + | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | + | **New issue URL** | Currently unused. Will be changed in a future release. | + +1. Click **Test settings and save changes**. + +After you configure and enable the Custom Issue Tracker service, you'll see a link on the GitLab +project pages that takes you to that custom issue tracker. ## Referencing issues -- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string in CAPS and `<ID>` -is a number used in the target project of the custom integration (for example, `PROJECT-143`). -- `ANYTHING` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. -- When building the hyperlink, the `ANYTHING` part is ignored, and links always point to the address +Issues are referenced with `<ANYTHING>-<ID>` (for example, `PROJECT-143`), where `<ANYTHING>` can be any string in CAPS, and `<ID>` +is a number used in the target project of the custom integration. + +`<ANYTHING>` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. + +When building the hyperlink, the `<ANYTHING>` part is ignored, and links always point to the address specified in `issues_url`, so in the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 2234727dd82..57c1e54e48c 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Generic alerts integration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. GitLab can accept alerts from any source via a generic webhook receiver. When you set up the generic alerts integration, a unique endpoint will @@ -18,6 +18,9 @@ create an issue with the payload in the body of the issue. You can always The entire payload will be posted in the issue discussion as a comment authored by the GitLab Alert Bot. +NOTE: **Note** +In GitLab versions 13.1 and greater, you can configure [External Prometheus instances](prometheus.md#external-prometheus-instances) to use this endpoint. + ## Setting up generic alerts To set up the generic alerts integration: @@ -28,7 +31,7 @@ To set up the generic alerts integration: ## Customizing the payload -You can customize the payload by sending the following parameters. All fields are optional: +You can customize the payload by sending the following parameters. All fields other than `title` are optional: | Property | Type | Description | | -------- | ---- | ----------- | @@ -39,6 +42,7 @@ You can customize the payload by sending the following parameters. All fields ar | `monitoring_tool` | String | The name of the associated monitoring tool. | | `hosts` | String or Array | One or more hosts, as to where this incident occurred. | | `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. | +| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | TIP: **Payload size:** Ensure your requests are smaller than the [payload application limits](../../../administration/instance_limits.md#generic-alert-json-payloads). @@ -65,5 +69,7 @@ Example payload: "service": "service affected", "monitoring_tool": "value", "hosts": "value", + "severity": "high", + "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385" } ``` diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 42d8eadd35e..f0977a4ea76 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,6 +1,6 @@ # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3836) in GitLab Premium 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab Premium 10.6. GitLab provides an integration for updating the pipeline statuses on GitHub. This is especially useful if using GitLab for CI/CD only. @@ -39,7 +39,7 @@ to configure pipelines to run for open pull requests. #### Static / dynamic status check names > - Introduced in GitLab 11.5: using static status check names as opt-in option. -> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/9931), static status check names is default behavior for new projects. +> - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. This makes it possible to mark these status checks as _Required_ on GitHub. With **Static status check names** enabled on the integration page, your diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 49b6a3f6450..7a827364d41 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -8,7 +8,7 @@ The GitLab Slack application is only configurable for GitLab.com. It will **not* work for on-premises installations where you can configure the [Slack slash commands](slack_slash_commands.md) service instead. We're planning to make this configurable for all GitLab installations, but there's -no ETA - see [#28164](https://gitlab.com/gitlab-org/gitlab/issues/28164). +no ETA - see [#28164](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). Slack provides a native application which you can enable via your project's integrations on GitLab.com. @@ -32,7 +32,7 @@ integration settings. Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your team](https://slack.com/help/articles/202035138). +docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). To enable GitLab's service for your Slack team: diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index f33833a9c93..f65b31150a9 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,6 +1,6 @@ # Hangouts Chat service -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/43756) in GitLab 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. The Hangouts Chat service sends notifications from GitLab to the room for which the webhook was created. diff --git a/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png b/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png Binary files differnew file mode 100644 index 00000000000..08d7d6603d2 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_yaml_validation_v13_1.png diff --git a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png Binary files differdeleted file mode 100644 index 8899852ed04..00000000000 --- a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v12_8.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png Binary files differnew file mode 100644 index 00000000000..56a0a508a1d --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_monitoring_dashboard_v13_1.png diff --git a/doc/user/project/integrations/img/related_links_v13_1.png b/doc/user/project/integrations/img/related_links_v13_1.png Binary files differnew file mode 100644 index 00000000000..4dc141f0e7f --- /dev/null +++ b/doc/user/project/integrations/img/related_links_v13_1.png diff --git a/doc/user/project/integrations/img/slack_configuration.png b/doc/user/project/integrations/img/slack_configuration.png Binary files differdeleted file mode 100644 index 4d5e6ae7856..00000000000 --- a/doc/user/project/integrations/img/slack_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 9fa92f19e4f..619c94b282b 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -3,7 +3,7 @@ An API token is needed when integrating with Jira Cloud, follow the steps below to create one: -1. Log in to <https://id.atlassian.com/manage/api-tokens> with your email address. +1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. NOTE: **Note** It is important that the user associated with this email address has *write* access diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 6c40e5b9696..0d17ff51372 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -25,7 +25,7 @@ Once enabled, GitLab will automatically detect metrics from known services in th ### Managed Prometheus on Kubernetes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28916) in GitLab 10.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. @@ -61,7 +61,7 @@ will help you to quickly create a deployment: 1. Navigate to your project's **CI/CD > Pipelines** page, and run a pipeline on any branch. 1. When the pipeline has run successfully, graphs will be available on the **Operations > Metrics** page. - + #### Using the Metrics Dashboard @@ -209,10 +209,19 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) - `ci_project_namespace` - `ci_project_path` - `ci_environment_name` +- `__range` NOTE: **Note:** Variables for Prometheus queries must be lowercase. +###### __range + +The `__range` variable is useful in Prometheus +[range vector selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#range-vector-selectors). +Its value is the total number of seconds in the dashboard's time range. +For example, if the dashboard time range is set to 8 hours, the value of +`__range` is `28800s`. + ##### User-defined variables [Variables can be defined](#templating-templating-properties) in a custom dashboard YAML file. @@ -244,7 +253,7 @@ http://gitlab.com/<user>/<project>/-/environments/<environment_id>/metrics?dashb #### Editing additional metrics from the dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/208976) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208976) in GitLab 12.9. You can edit existing additional custom metrics by clicking the **{ellipsis_v}** **More actions** dropdown and selecting **Edit metric**. @@ -252,7 +261,7 @@ You can edit existing additional custom metrics by clicking the **{ellipsis_v}** ### Defining custom dashboards per project -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/59974) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. By default, all projects include a GitLab-defined Prometheus dashboard, which includes a few key metrics, but you can also define your own custom dashboards. @@ -308,8 +317,8 @@ supported and will not be available in the UI. #### Duplicating a GitLab-defined dashboard -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/37238) in GitLab 12.7. -> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7. +> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. You can save a complete copy of a GitLab defined dashboard along with all custom metrics added to it. Resulting `.yml` file can be customized and adapted to your project. @@ -326,6 +335,42 @@ new branch. If you select your **default** branch, the new dashboard becomes immediately available. If you select another branch, this branch should be merged to your **default** branch first. +#### Dashboard YAML syntax validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33202) in GitLab 13.1. + +To confirm your dashboard definition contains valid YAML syntax: + +1. Navigate to **{doc-text}** **Repository > Files**. +1. Navigate to your dashboard file in your repository. +1. Review the information pane about the file, displayed above the file contents. + +Files with valid syntax display **Metrics Dashboard YAML definition is valid**, +and files with invalid syntax display **Metrics Dashboard YAML definition is invalid**. + + + +When **Metrics Dashboard YAML definition is invalid** at least one of the following messages is displayed: + +1. `dashboard: can't be blank` [learn more](#dashboard-top-level-properties) +1. `panel_groups: can't be blank` [learn more](#dashboard-top-level-properties) +1. `group: can't be blank` [learn more](#panel-group-panel_groups-properties) +1. `panels: can't be blank` [learn more](#panel-group-panel_groups-properties) +1. `metrics: can't be blank` [learn more](#panel-panels-properties) +1. `title: can't be blank` [learn more](#panel-panels-properties) +1. `query: can't be blank` [learn more](#metrics-metrics-properties) +1. `query_range: can't be blank` [learn more](#metrics-metrics-properties) +1. `unit: can't be blank` [learn more](#metrics-metrics-properties) +1. `YAML syntax: The parsed YAML is too big` + + This is displayed when the YAML file is larger than 1 MB. + +1. `YAML syntax: Invalid configuration format` + + This is displayed when the YAML file is empty or does not contain valid YAML. + +Metrics Dashboard YAML definition validation information is also available as a [GraphQL API field](../../../api/graphql/reference/index.md#metricsdashboard) + #### Dashboard YAML properties Dashboards have several components: @@ -342,16 +387,27 @@ The following tables outline the details of expected properties. | ------ | ------ | ------ | ------ | | `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | | `panel_groups` | array | yes | The panel groups which should be on the dashboard. | -| `templating` | Hash | no | Top level key under which templating related options can be added. | +| `templating` | hash | no | Top level key under which templating related options can be added. | +| `links` | array | no | Add links to display on the dashboard. | ##### **Templating (`templating`) properties** | Property | Type | Required | Description | | -------- | ---- | -------- | ----------- | -| `variables` | Hash | no | Variables can be defined here. | +| `variables` | hash | yes | Variables can be defined here. | Read the documentation on [templating](#templating-variables-for-metrics-dashboards). +##### **Links (`links`) properties** + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `url` | string | yes | The address of the link. | +| `title` | string | no | Display title for the link. | +| `type` | string | no | Type of the link. Specifies the link type, can be: `grafana` | + +Read the documentation on [links](#add-related-links-to-custom-dashboards). + ##### **Panel group (`panel_groups`) properties** | Property | Type | Required | Description | @@ -371,6 +427,7 @@ Read the documentation on [templating](#templating-variables-for-metrics-dashboa | `max_value` | number | no | Denominator value used for calculating [percentile based results](#percentile-based-results) | | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | +| `links` | array | no | Add links to display on the chart's [context menu](#chart-context-menu). | ##### **Axis (`panels[].y_axis`) properties** @@ -472,7 +529,7 @@ Note the following properties:  -Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. +Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. ##### Anomaly chart @@ -574,7 +631,7 @@ Note the following properties: ##### Stacked column -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30583) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30583) in GitLab 12.8. To add a stacked column panel type to a dashboard, look at the following sample dashboard file: @@ -639,7 +696,7 @@ Note the following properties: ###### Percentile based results -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201946) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201946) in GitLab 12.8. Query results sometimes need to be represented as a percentage value out of 100. You can use the `max_value` property at the root of the panel definition: @@ -662,7 +719,7 @@ For example, if you have a query value of `53.6`, adding `%` as the unit results ##### Heatmaps -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30581) in GitLab 12.5. To add a heatmap panel type to a dashboard, look at the following sample dashboard file: @@ -699,7 +756,7 @@ Templating variables can be used to make your metrics dashboard more versatile. [dashboard YAML](#dashboard-top-level-properties). Define your variables in the `variables` key, under `templating`. The value of the `variables` key should be a hash, and each key under `variables` -defines a templating variable on the dashboard. +defines a templating variable on the dashboard, and may contain alphanumeric and underscore characters. A variable can be used in a Prometheus query in the same dashboard using the syntax described [here](#using-variables). @@ -766,7 +823,7 @@ templating: ###### Full syntax -This example creates a variable called `variable1`, with a default value of `var1_option_2`. +This example creates a variable called `variable1`, with a default value of `value_option_2`. The label for the text box on the UI will be the value of the `label` key. The dashboard UI will display a dropdown with `Option 1` and `Option 2` as the choices. @@ -789,9 +846,50 @@ templating: default: true # (Optional) This option should be the default value of this variable. ``` +### Add related links to custom dashboards + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216385) in GitLab 13.1. + +You can embed links to other dashboards or external services in your custom +dashboard by adding **Related links** to your dashboard's YAML file. Related links +open in the same tab as the dashboard. Related links can be displayed in the +following locations on your dashboard: + +- At the top of your dashboard as the top level [`links` dashboard property](#dashboard-top-level-properties). +- In charts context menus as the [`links` property of a panel](#panel-panels-properties). + +Related links can contain the following attributes: + +- `url`: The full URL to the link. Required. +- `title`: A phrase describing the link. Optional. If this attribute is not set, + the full URL is used for the link title. +- `type`: A string declaring the type of link. Optional. If set to `grafana`, the + dashboard's time range values are converted to Grafana's time range format and + appended to the `url`. + +The dashboard's time range is appended to the `url` as URL parameters. + +The following example shows two related links (`GitLab.com` and `GitLab Documentation`) +added to a dashboard: + + + +#### Links Syntax + +```yaml +links: + - title: GitLab.com + url: https://gitlab.com + - title: GitLab Documentation + url: https://docs.gitlab.com + - title: Public Grafana playground dashboard + url: https://play.grafana.org/d/000000012/grafana-play-home?orgId=1 + type: grafana +``` + ### View and edit the source file of a custom dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5. When viewing a custom dashboard of a project, you can view the original `.yml` file by clicking on the **Edit dashboard** button. @@ -812,7 +910,7 @@ The options are: ### Dashboard Annotations -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/215224) in GitLab 13.0. You can use **Metrics Dashboard Annotations** to mark any important events on @@ -827,6 +925,14 @@ You can create annotations by making requests to the  +#### Retention policy + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211433) in GitLab 13.01. + +To avoid excessive storage space consumption by stale annotations, records attached +to time periods older than two weeks are removed daily. This recurring background +job runs at 1:00 a.m. local server time. + ### Expand panel > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0. @@ -839,7 +945,7 @@ browser, or pressing the <kbd>Esc</kbd> key. ### View Logs **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/122013) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8. If you have [Logs](../clusters/kubernetes_pod_logs.md) enabled, you can navigate from the charts in the dashboard to view Logs by @@ -881,8 +987,8 @@ To remove the alert, click back on the alert icon for the desired metric, and cl #### External Prometheus instances ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. ->- [Moved](https://gitlab.com/gitlab-org/gitlab/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. +>- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. For manually configured Prometheus servers, a notify endpoint is provided to use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. This contains the *URL* and *Authorization Key*. The **Reset Key** button will invalidate the key and generate a new one. @@ -903,12 +1009,15 @@ receivers: In order for GitLab to associate your alerts with an [environment](../../../ci/environments/index.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. +NOTE: **Note** +In GitLab versions 13.1 and greater, you can configure your manually configured Prometheus server to use the [Generic alerts integration](generic_alerts.md). + ### Taking action on incidents **(ULTIMATE)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. ->- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. -Alerts can be used to trigger actions, like opening an issue automatically (enabled by default since `12.1`). To configure the actions: +Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: 1. Navigate to your project's **Settings > Operations > Incidents**. 1. Enable the option to create issues. @@ -931,14 +1040,14 @@ When GitLab receives a **Recovery Alert**, it will automatically close the assoc To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. -Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. +Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. If the metric exceeds the threshold of the alert for over 5 minutes, an email will be sent to all [Maintainers and Owners](../../permissions.md#project-members-permissions) of the project. ## Determining the performance impact of a merge > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. -> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/issues/27439) of the 30 minute averages. +> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. Developers can view the performance impact of their changes within the merge request workflow. @@ -1031,7 +1140,7 @@ For [manually configured Prometheus instances](#manual-configuration-of-promethe ### Embedding Cluster Health Charts **(ULTIMATE)** -> [Introduced](<https://gitlab.com/gitlab-org/gitlab/issues/40997>) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/40997>) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. [Cluster Health Metrics](../clusters/index.md#monitoring-your-kubernetes-cluster-ultimate) can also be embedded in [GitLab-flavored Markdown](../../markdown.md). @@ -1075,7 +1184,7 @@ This will render like so: #### Embedding charts via integration with Grafana HTTP API -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31376) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5. Each project can support integration with one Grafana instance. This configuration allows a user to copy a link to a panel in Grafana, then paste it into a GitLab Markdown field. The chart will be rendered in the GitLab chart format. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index 691d20e5de2..7b216ced1cc 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Unit formats reference -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201999) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201999) in GitLab 12.9. You can select units to format your charts by adding `format` to your [axis configuration](prometheus.md#dashboard-yaml-properties). @@ -19,7 +19,7 @@ Currently, your [internationalization and localization options](https://en.wikip For generic or default data, numbers are formatted according to the current locale in [engineering notation](https://en.wikipedia.org/wiki/Engineering_notation). -While an [engineering notation exists for the web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat), GitLab uses a version based off the [scientific notation](https://en.wikipedia.org/wiki/Scientific_notation). GitLab formatting acts in accordance with SI prefixes. For example, using GitLab notation, `1500.00` becomes `1.5k` instead of `1.5E3`. Keep this distinction in mind when using the engineering notation for your metrics. +While an [engineering notation exists for the web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), GitLab uses a version based off the [scientific notation](https://en.wikipedia.org/wiki/Scientific_notation). GitLab formatting acts in accordance with SI prefixes. For example, using GitLab notation, `1500.00` becomes `1.5k` instead of `1.5E3`. Keep this distinction in mind when using the engineering notation for your metrics. Formats: `engineering` diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 419340c14ef..79fc8eceddf 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -23,7 +23,23 @@ The Slack Notifications Service allows your GitLab project to send events (e.g. Your Slack team will now start receiving GitLab event notifications as configured. - +### Triggers available for Slack notifications + +The following triggers are available for Slack notifications: + +- **Push**: Triggered by a push to the repository. +- **Issue**: Triggered when an issue is created, updated, or closed. +- **Confidential issue**: Triggered when a confidential issue is created, + updated, or closed. +- **Merge request**: Triggered when a merge request is created, updated, or + merged. +- **Note**: Triggered when someone adds a comment. +- **Confidential note**: Triggered when someone adds a confidential note. +- **Tag push**: Triggered when a new tag is pushed to the repository. +- **Pipeline**: Triggered when a pipeline status changes. +- **Wiki page**: Triggered when a wiki page is created or updated. +- **Deployment**: Triggered when a deployment finishes. +- **Alert**: Triggered when a new, unique alert is recorded. ## Troubleshooting diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index a6e688887b6..10735e33746 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ You can configure GitLab to send notifications to a Webex Teams space. ## Create a webhook for the space -1. Go to the [Incoming Webooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems). 1. Click **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space that will receive the notifications. 1. Click **ADD**. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 89e84dda0e8..5a0ca03a646 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -89,7 +89,7 @@ You can turn this off in the webhook settings in your GitLab projects. ## Branch filtering -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/20338) in GitLab 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. Push events can be filtered by branch using a branch name or wildcard pattern to limit which push events are sent to your webhook endpoint. By default the diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 9903a711987..89b17609698 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Issue Boards > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). @@ -190,7 +196,7 @@ as shown in the following table: ### Multiple issue boards > - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. > - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). Multiple issue boards allow for more than one issue board for a given project or group. @@ -290,7 +296,7 @@ Multiple group issue boards were originally [introduced](https://about.gitlab.co ### Assignee lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. Like in a regular list that shows all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. @@ -311,7 +317,7 @@ To remove an assignee list, just as with a label list, click the trash icon. ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. To add a milestone list: @@ -330,7 +336,7 @@ As in other list types, click the trash icon to remove a list. ## Work In Progress limits **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11403) in GitLab 12.7 +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 You can set Work In Progress (WIP) limits per issues list. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. @@ -352,7 +358,7 @@ To set a WIP limit for a list: ## Blocked issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34723) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked status. @@ -370,7 +376,7 @@ status. - [Filter issues](#filter-issues) that appear across your issue board. - [Create workflows](#create-workflows). - [Drag issues between lists](#drag-issues-between-lists). -- [Mulit-select issue cards](#multi-select-issue-cards). +- [Multi-select issue cards](#multi-select-issue-cards). - [Re-order issues in lists](#issue-ordering-in-a-list). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). @@ -501,7 +507,7 @@ When dragging issues between lists, different behavior occurs depending on the s ### Multi-select issue cards -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18954) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index 3bfd24c9654..a026854a947 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Associate a Zoom meeting with an issue > [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 a292ce64af9..602a6d79848 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Confidential issues > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3282) in GitLab 8.6. @@ -80,7 +86,7 @@ project's search results respectively. ## Merge Requests for Confidential Issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/58583) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. To help prevent confidential information being leaked from a public project in the process of resolving a confidential issue, confidential issues can be diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index e774fd4480b..6cc31a45309 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Crosslinking Issues Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 64f56221632..981c2a7c34a 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -3,10 +3,6 @@ > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. -CAUTION: **Warning:** -This an **alpha** feature and is subject to change at any time without -prior notice. - ## Overview Design Management allows you to upload design assets (wireframes, mockups, etc.) @@ -45,19 +41,19 @@ If the requirements are not met, the **Designs** tab displays a message to the u Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. -Support for [SVG files](https://gitlab.com/gitlab-org/gitlab/issues/12771) -and [PDFs](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. +Support for [SVG files](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) +and [PDFs](https://gitlab.com/gitlab-org/gitlab/-/issues/32811) is planned for a future release. ## Limitations - Design uploads are limited to 10 files at a time. - Design Management data - [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/issues/13429) yet. -- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/issues/13426) - when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab/issues/13427) + [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. +- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/-/issues/13426) + when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) when an issue is deleted. - From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) - by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/issues/32467). + by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). - Only the latest version of the designs can be deleted. - Deleted designs cannot be recovered but you can see them on previous designs versions. @@ -71,8 +67,8 @@ Navigate to the **Design Management** page from any issue by clicking the **Desi To upload design images, click the **Upload Designs** button and select images to upload. -[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, -you can drag and drop designs onto the dedicated dropzone to upload them. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, +you can drag and drop designs onto the dedicated drop zone to upload them.  @@ -91,7 +87,7 @@ Copy-and-pasting has some limitations: - Copy/pasting designs is not supported on Internet Explorer. Designs with the same filename as an existing uploaded design will create a new version -of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, +of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, provided the filenames are the same. Designs cannot be added if the issue has been moved, or its @@ -123,19 +119,19 @@ to help summarize changes between versions. ### Exploring designs by zooming -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13217) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. Designs can be explored in greater detail by zooming in and out of the image. Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. While zoomed, you can still [start new discussions](#starting-discussions-on-designs) on the image, and see any existing ones. -[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197324) in GitLab 12.10, while zoomed in, +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10, while zoomed in, you can click-and-drag on the image to move around it.  ## Deleting designs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11089) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. There are two ways to delete designs: manually delete them individually, or select a few of them to delete at once, @@ -169,7 +165,7 @@ A pin is added to the image, identifying the discussion's location.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8, +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8, you can adjust a pin's position by dragging it around the image. This is useful for when your design layout has changed between revisions, or if you need to move an existing pin to add a new one in its place. @@ -180,3 +176,60 @@ Different discussions have different pin numbers: From GitLab 12.5 on, new discussions will be outputted to the issue activity, so that everyone involved can participate in the discussion. + +## Resolve Design threads + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. + +Discussion threads can be resolved on Designs. You can mark a thread as resolved +or unresolved by clicking the **Resolve thread** icon at the first comment of the +discussion. + + + +Pinned comments can also be resolved or unresolved in their threads. +When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve +the thread once published. + + + +## Referring to designs in Markdown + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in **GitLab 13.1**. +> - It is deployed behind a feature flag, disabled by default. +> - It is disabled on GitLab.com. +> - It is not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references-core-only). **(CORE ONLY)** + +We support referring to designs in [Markdown](../../markdown.md), which is available +throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. + +At present, full URL references are supported. For example, if we refer to a design +somewhere with: + +```markdown +See https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png +``` + +This will be rendered as: + +> See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) + +### Enable or disable design references **(CORE ONLY)** + +Design reference parsing 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 for your instance. + +To enable it: + +```ruby +Feature.enable(:design_management_reference_filter_gfm_pipeline) +``` + +To disable it: + +```ruby +Feature.disable(:design_management_reference_filter_gfm_pipeline) +``` diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 0be0cdd11bd..56fb4ca5cc7 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Due dates > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3614) in GitLab 8.7. diff --git a/doc/user/project/issues/img/new_issue.png b/doc/user/project/issues/img/new_issue.png Binary files differdeleted file mode 100644 index 07d65a93070..00000000000 --- a/doc/user/project/issues/img/new_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_v13_1.png b/doc/user/project/issues/img/new_issue_v13_1.png Binary files differnew file mode 100644 index 00000000000..a66846c234e --- /dev/null +++ b/doc/user/project/issues/img/new_issue_v13_1.png diff --git a/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png b/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png Binary files differnew file mode 100644 index 00000000000..bd9d1f7a77c --- /dev/null +++ b/doc/user/project/issues/img/resolve_design-discussion_checkbox_v13_1.png diff --git a/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png b/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png Binary files differnew file mode 100644 index 00000000000..5cd005f0799 --- /dev/null +++ b/doc/user/project/issues/img/resolve_design-discussion_icon_v13_1.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 22221531360..06a80672769 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Issues Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. @@ -151,7 +157,7 @@ context, such as past work, dependencies, or duplicates. ### Crosslinking issues -You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another +You can [cross-link issues](crosslinking_issues.md) by referencing an issue from another issue or merge request by including its URL or ID. The referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR. @@ -173,7 +179,7 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. ### Health status **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 65e21566d5d..6d34f91d37f 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Issue Data and Actions Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. @@ -185,7 +191,7 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [Since GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/10103), changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** +> [Since GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103), changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** ### Mentions @@ -296,7 +302,7 @@ You can also close the issue from here, so you don't need to scroll to the top o ### Zoom meetings -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31103) in GitLab 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31103) in GitLab 12.3. You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove_zoom` [quick actions](../quick_actions.md) as part of [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). @@ -305,3 +311,9 @@ Attaching a [Zoom](https://zoom.us) call an issue results in a **Join Zoom meeting** button at the top of the issue, just under the header. Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). + +### Publish an issue **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +If a status page application is associated with the project, you can use the `/publish` [quick action](../quick_actions.md) to publish the issue. Refer to [GitLab Status Page](../status_page/index.md) for more information. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 74f607dd407..23c1520294d 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -1,5 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' +stage: Plan +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/#designated-technical-writers --- # Issue weight **(STARTER)** diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 4e329889e7c..08e3164b2eb 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,21 +1,28 @@ -# Managing Issues +--- +stage: Plan +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/#designated-technical-writers +--- + +# Managing issues [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues), [closing](#closing-issues), and [deleting](#deleting-issues) are key actions that you can do with issues. -## Create a new Issue +## Create a new issue -When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), as illustrated below. If you know -the values you want to assign to an issue, you can use the [Quick actions](../quick_actions.md) -feature to input values, instead of selecting them from lists. +When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), +as illustrated below. If you know the values you want to assign to an issue, you can use the +[Quick actions](../quick_actions.md) feature to input values, instead of selecting them from lists. - +While creating an issue, you can associate it to an existing epic from current group by +selecting it using **Epic** dropdown. -### Accessing the new Issue form +### Accessing the New Issue form -There are many ways to get to the new Issue form from within a project: +There are many ways to get to the New Issue form from within a project: - Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: @@ -36,9 +43,28 @@ There are many ways to get to the new Issue form from within a project:  +### Elements of the New Issue form + +> Ability to add the new issue to an epic [was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) +> in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. + + + +When you're creating a new issue, these are the fields you can fill in: + +- Title +- Description +- Checkbox to make the issue confidential +- Assignee +- Weight +- Epic **(PREMIUM)** +- Due date +- Milestone +- Labels + ### New issue from the group-level Issue Tracker -Go to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker +Go to the Group dashboard and click **Issues** in the sidebar to visit the Issue Tracker for all projects in your Group. Select the project you'd like to add an issue for using the dropdown button at the top-right of the page. @@ -107,11 +133,11 @@ field). Follow these examples to form your new issue URL with prefilled fields. - For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` + and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` - For a new issue in the GitLab Community Edition project with a pre-filled title - and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` + and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` - For a new issue in the GitLab Community Edition project with a pre-filled title, - a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` + a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` ## Moving Issues @@ -147,7 +173,7 @@ issues.each do |issue| end; nil ``` -## Closing Issues +## Closing issues When you decide that an issue is resolved, or no longer needed, you can close the issue using the close button: @@ -226,6 +252,8 @@ when used from the command line with `git commit -m`. #### Disabling automatic issue closing +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. + The automatic issue closing feature can be disabled on a per-project basis within the [project's repository settings](../settings/index.md). Referenced issues will still be displayed as such but won't be closed automatically. @@ -243,7 +271,7 @@ In order to change the default issue closing pattern, GitLab administrators must [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. -## Deleting Issues +## Deleting issues > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2982) in GitLab 8.6 diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index dff6a6031d7..c11977f5bee 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,6 +1,12 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Multiple Assignees for Issues **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). ## Overview diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 8002b528a80..445c28492df 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Related issues **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index d52b629bfed..7cbd9906800 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,4 +1,10 @@ -# Sorting and Ordering Issue Lists +--- +stage: Plan +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/#designated-technical-writers +--- + +# Sorting and ordering issue lists You can sort a list of issues several ways, including by issue creation date, milestone due date, etc. The available sorting options can change based on the context of the list. @@ -9,7 +15,7 @@ similar to [issue boards](../issue_board.md#issue-ordering-in-a-list). ## Manual sorting -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/62178) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. When you select **Manual** sorting, you can change the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index f3b59147d5b..406938519b1 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,3 +1,9 @@ +--- +stage: Plan +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/#designated-technical-writers +--- + # Labels ## Overview @@ -131,7 +137,7 @@ to the project: ## Scoped labels **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. Scoped labels allow teams to use the label feature to annotate issues, merge requests and epics with mutually exclusive labels. This can enable more complicated workflows @@ -203,8 +209,8 @@ to label notifications for the project only, or the whole group. ## Label priority -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14189) in GitLab 8.9. -> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/issues/14523) considers changing this. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14189) in GitLab 8.9. +> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. Labels can have relative priorities, which are used in the **Label priority** and **Priority** sort orders of the epic, issue, and merge request list pages. Prioritization @@ -229,7 +235,7 @@ If you sort by `Label priority`, GitLab uses this sort comparison order: 1. Items without a prioritized label. Ties are broken arbitrarily. Note that only the highest prioritized label is checked, -and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/issues/14523) +and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) for more information.  diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 9020dc335b6..787a74b0065 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -8,7 +8,7 @@ You should have Maintainer or Owner [permissions](../../permissions.md) to add or import a new user to your project. To view, edit, add, and remove project's members, go to your -project's **Settings > Members**. +project's **Members**. ## Inherited membership @@ -27,7 +27,7 @@ From the image above, we can deduce the following things: - Administrator is the Owner and member of **all** groups and for that reason, there is an indication of an ancestor group and inherited Owner permissions. -[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/21727), you can filter this list +[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/21727), you can filter this list using the dropdown on the right side:  diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d0ceac3e1f3..033d69cbbfa 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -18,7 +18,7 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: -1. For 'Project Acme' use the left navigation menu to go to **Settings > Members** +1. For 'Project Acme' use the left navigation menu to go to **Members**  diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 427761281f6..417b85a6082 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -25,16 +25,6 @@ Accessibility Report in the merge request widget area:  -This widget comes with the `:accessibility_report_view` feature flag disabled by default while we test feature stability. -Once we have determined the widget is stable, this feature will be enabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -Feature.enable(:accessibility_report_view) -``` - ## Configure Accessibility Testing This example shows how to run [pa11y](https://pa11y.org/) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 0fa3d7be265..390d480724d 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -60,7 +60,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [docker-in-docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). 1. After configuring the Runner, add a new job to `.gitlab-ci.yml` that generates the expected report. 1. Define the `performance` job according to your version of GitLab: @@ -125,7 +125,7 @@ Key metrics are automatically extracted and shown in the merge request widget. ### Configuring degradation threshold -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27599) in GitLab 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 3e76b9ec6b9..6685c50c1ed 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -33,7 +33,7 @@ request thread crosslinking the new commit and the existing merge request. Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. NOTE: **Note:** -We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/issues/202215) is planned for a future release. +We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. ## Cherry-picking a commit diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index beb90e30906..7b4d4b668d5 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -12,7 +12,7 @@ source code quality using GitLab Code Quality. Code Quality: - Uses [Code Climate Engines](https://codeclimate.com), which are - free and open source. Code Quality doesn't require a Code Climate + 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 @@ -67,10 +67,10 @@ This example shows how to run Code Quality on your code by using GitLab CI/CD an First, you need GitLab Runner configured: -- For the [docker-in-docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). +- For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). - With enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. -Once you set up the Runner, include the CodeQuality template in your CI config: +Once you set up the Runner, include the Code Quality template in your CI configuration: ```yaml include: @@ -80,10 +80,9 @@ include: The above example will create a `code_quality` job in your CI/CD pipeline which will scan your source code for code quality issues. The report will be saved as a [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter) -that you can later download and analyze. Due to implementation limitations we always -take the latest Code Quality artifact available. +that you can later download and analyze. -It is also possible to override the URL to the Code Quality image by +It's also possible to override the URL to the Code Quality image by setting the `CODE_QUALITY_IMAGE` variable. This is particularly useful if you want to lock in a specific version of Code Quality, or use a fork of it: @@ -108,7 +107,7 @@ code_quality: paths: [gl-code-quality-report.json] ``` -The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI config, like so: +The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI configuration, like so: ```yaml stages: @@ -120,7 +119,7 @@ This information will be automatically extracted and shown right in the merge re CAUTION: **Caution:** On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged docker commands on the Runner +definition they will be able to execute privileged Docker commands on the Runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. @@ -129,9 +128,8 @@ allowing access only to trusted actors. CAUTION: **Caution:** Before GitLab 11.5, Code Quality job and artifact had to be named specifically to automatically extract report data and show it in the merge request widget. While these -old job definitions are still maintained they have been deprecated and may be removed -in the next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` -configuration to reflect that change. +old job definitions are still maintained they have been deprecated and are no longer supported on GitLab 12.0 or higher. +You're advised to update your `.gitlab-ci.yml` configuration to reflect that change. For GitLab 11.5 and later, the job should look like: @@ -157,7 +155,7 @@ code_quality: In GitLab 12.6, Code Quality switched to the [new versioning scheme](https://gitlab.com/gitlab-org/ci-cd/codequality#versioning-and-release-cycle). -It is highly recommended to include the Code Quality template as shown in the +It's highly recommended to include the Code Quality template as shown in the [example configuration](#example-configuration), which uses the new versioning scheme. If not using the template, the `SP_VERSION` variable can be hardcoded to use the new image versions: @@ -241,7 +239,7 @@ do this: [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter). 1. Configure your tool to generate the Code Quality report artifact as a JSON - file that implements subset of the [Code Climate + file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). The Code Quality report artifact JSON file must contain an array of objects @@ -288,28 +286,28 @@ Once the Code Quality job has completed: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. -If multiple jobs in a pipeline generate a code quality artifact, only the artifact from -the last created job (the job with the largest job ID) is used. To avoid confusion, -configure only one job to generate a code quality artifact. +## Troubleshooting -If the Code Quality report doesn't have anything to compare to, no information -will be displayed in the merge request area. That is the case when you add the -Code Quality job in your `.gitlab-ci.yml` for the very first time. -Consecutive merge requests will have something to compare to and the Code Quality -report will be shown properly. +### No Code Quality report is displayed in a Merge Request -These reports will only be available as long as the Code Quality artifact(s) required to generate -them are also available. See -[`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) for more details. +This can be due to multiple reasons: -<!-- ## Troubleshooting +- You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not + have anything to compare to yet, so no information can be displayed. Future merge + requests will have something to compare to. +- If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), + nothing will be displayed. +- The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD + setting can cause the Code Quality artifact(s) to expire faster than desired. +- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). + As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) + that are [ignored by GitLab](#implementing-a-custom-tool). You can: + - Configure the Code Quality tool to not output those types. + - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to + edit the `codeclimate.json` before the job completes. -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. +### Only a single Code Quality report is displayed, but more are defined -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. --> +GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). +If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. +To avoid confusion, configure only one job to generate a `codeclimate.json`. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 544727380e7..50d5decc2cc 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -12,8 +12,8 @@ to familiarize yourself with the concept, the terminology, and to learn what you can do with them. Every merge request starts by creating a branch. You can either -do it locally through the command line, via a Git CLI application, -or through the GitLab UI. +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). This document describes the several ways to create a merge request. @@ -100,7 +100,7 @@ button to open the [**New Merge Request** page](#new-merge-request-page). A new merge request will be started using the current branch as the source, and the default branch in the current project as the target. -## New merge request from you local environment +## 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 diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 0ab8d31403e..32eb0c73ed4 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -67,7 +67,7 @@ Once you have created the merge request, you can also: - Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). - Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews-premium) in order to create multiple comments on a diff and publish them once you're ready. **(PREMIUM)** +- Perform a [Review](../../discussions/index.md#merge-request-reviews) in order to create multiple comments on a diff and publish them once you're ready. - Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). @@ -86,7 +86,7 @@ and the merge request will be added to their #### Multiple assignees **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2038414dab8..5d2813f5bfc 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -54,7 +54,7 @@ To get started, read the [introduction to merge requests](getting_started.md). ## Merge request navigation tabs at the top -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33813) in GitLab 12.6. This positioning is experimental. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. So far, the navigation tabs present in merge requests to display **Discussion**, **Commits**, **Pipelines**, and **Changes** were located after the merge request @@ -86,35 +86,7 @@ See the features at your disposal to [review and manage merge requests](reviewin ## Testing and reports in merge requests -GitLab has the ability to test the changes included in a merge request, and can display -or link to useful information directly in the merge request page: - -| Feature | Description | -|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests | -| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | -| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../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. | -| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | -| [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. | -| [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. | - -### Security Reports **(ULTIMATE)** - -In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), -generated by scanning and reporting any vulnerabilities found in your project: - -| Feature | Description | -|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| -| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | -| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | -| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | +Learn about the options for [testing and reports](testing_and_reports_in_merge_requests.md) on the changes in a merge request. ## Authorization for merge requests diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index e5896e62397..dd90449cd86 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -34,10 +34,12 @@ minimum number of required approvers can still be set in the [project settings f ### Eligible approvers -The following can approve merge requests: +The following users can approve merge requests: -- Users being added as approvers at project or merge request level. -- [Code owners](#code-owners-as-eligible-approvers) to the files changed by the merge request. +- Users who have been added as approvers at the project or merge request levels with + developer or higher [permissions](../../permissions.md). +- [Code owners](#code-owners-as-eligible-approvers) of the files changed by the merge request + that have developer or higher [permissions](../../permissions.md). An individual user can be added as an approver for a project if they are a member of: @@ -46,7 +48,7 @@ An individual user can be added as an approver for a project if they are a membe - A group that has access to the project via a [share](../members/share_project_with_groups.md). A group of users can also be added as approvers. In the future, group approvers may be -[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/issues/2048). +[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, then that user is just counted once. The merge request author, as well as users who have committed @@ -68,7 +70,7 @@ were not explicitly listed in the approval rules. If you add [Code Owners](../code_owners.md) to your repository, the owners to the corresponding files will become eligible approvers, together with members with Developer -or higher permissions. +or higher [permissions](../../permissions.md). To enable this merge request approval rule: @@ -127,7 +129,7 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- ### Multiple approval rules **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. In GitLab Premium, it is possible to have multiple approval rules per merge request, as well as multiple default approval rules per project. @@ -149,7 +151,7 @@ reduce the number of approvals left for all rules that the approver belongs to. ### Scoped to Protected Branch **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. Approval rules are often only relevant to specific branches, like `master`. When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) @@ -222,7 +224,7 @@ from the UI. However, approvals will be reset if the target branch is changed. ### Allowing merge request authors to approve their own merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. You can allow merge request authors to self-approve merge requests. Authors also need to be included in the approvers list in order to be able to @@ -234,7 +236,7 @@ approve their merge request. To enable this feature: ### Prevent approval of merge requests by their committers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. You can prevent users that have committed to a merge request from approving it. To enable this feature: @@ -244,7 +246,12 @@ enable this feature: ### Require authentication when approving a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. + +NOTE: **Note:** +To require authentication when approving a merge request, you must enable +**Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). +in the Admin area. You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined @@ -264,7 +271,7 @@ For more information, see ## Enabling the new approvals interface -Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/issues/10685), an updated approvals +Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/10685), an updated approvals interface is available by default. In versions older than 12.0, the updated interface is not available unless the `approval_rules` feature flag is enabled, which can be done from the Rails console by instance administrators. diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 66a1d2ac6af..a1012e27d32 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -4,7 +4,7 @@ type: reference, concepts # Merge Request dependencies **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge Requests dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. @@ -94,9 +94,9 @@ merge. ## Limitations -- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/issues/12551) -- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/issues/12549) -- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/issues/11393) +- API support: [issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551) +- Dependencies are not preserved across project export/import: [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549) +- Complex merge order dependencies are not supported: [issue #11393](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) The last item merits a little more explanation. Dependencies between merge requests can be described as a graph of relationships. The simplest possible 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 50412e0b319..d45ccdc9be9 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -59,11 +59,24 @@ merge request from the UI, until you make all relevant jobs pass.  +### Skipped pipelines + +> [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 +merge requests from being merged. To change this behavior: + +1. Navigate to your project's **Settings > General** page. +1. Expand the **Merge requests** section. +1. In the **Merge checks** subsection, ensure **Pipelines must succeed** is checked. +1. In the **Merge checks** subsection, select the **Skipped pipelines are considered successful** checkbox. +1. Press **Save** for the changes to take effect. + ### 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#onlyexcept-advanced) rules are used and they don't generate any pipelines. -Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/issues/54226) and that it's successful. +Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) and that it's successful. For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs: diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index fdcb1049ef7..a3ad41d8dd8 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -82,6 +82,10 @@ to expand the entire file.  +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205401) in GitLab 13.1, when viewing a +merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the +entire content by clicking **Show file contents**. + ### Ignore whitespace changes in Merge Request diff view If you click the **Hide whitespace changes** button, you can see the diff @@ -96,7 +100,7 @@ whitespace changes. ## Perform inline code reviews -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. GitLab provides a way of leaving comments in any part of the file being changed in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. @@ -108,7 +112,7 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, you will be able to see: -- Both pre and post-merge pipelines and the environment information if any. +- Both pre-merge and post-merge pipelines and the environment information if any. - Which deployments are in progress. If there's an [environment](../../../ci/environments/index.md) and the application is diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 84d60fca72d..1c0e698aba5 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -4,7 +4,7 @@ type: reference, howto # Test Coverage Visualization -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3708) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test coverage information of your favorite testing or coverage-analysis tool, and visualize @@ -67,7 +67,7 @@ test: This feature comes with the `:coverage_report_view` feature flag disabled by default. This feature is disabled due to some performance issues with very large -data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/issues/211410) +data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) is resolved, the feature will be enabled by default. To enable this feature, ask a GitLab administrator with Rails console access to 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 new file mode 100644 index 00000000000..f7614ed7996 --- /dev/null +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -0,0 +1,36 @@ +--- +type: index +description: "Test your code and display reports in merge requests" +--- + +# Tests and reports in merge requests + +GitLab has the ability to test the changes included in a feature branch and display reports +or link to useful information directly from merge requests: + +| Feature | Description | +|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | +| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | +| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | +| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../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. | +| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | +| [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. | +| [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. | + +## Security Reports **(ULTIMATE)** + +In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), +generated by scanning and reporting any vulnerabilities found in your project: + +| Feature | Description | +|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| +| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | +| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | +| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 84934148bdc..9581c974414 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -37,7 +37,7 @@ changes appears as a system note. ## Find the merge request that introduced a change -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2383) in GitLab 10.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. When viewing the commit details page, GitLab will link to the merge request (or merge requests, if it's in more than one) containing that commit. @@ -48,7 +48,7 @@ request, they will not be linked. ## `HEAD` comparison mode for Merge Requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27008) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. Merge Requests, particularly the **Changes** tab, is where source code is reviewed and discussed. In circumstances where the target branch was @@ -62,7 +62,7 @@ shows a diff calculated by simulating how it would look like once merged - a mor representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down by selecting **master (HEAD)**. In the future it will -[replace](https://gitlab.com/gitlab-org/gitlab/issues/198458) the +[replace](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the current default comparison.  diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index e9f23899068..e28ba1d2d5f 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,5 +1,8 @@ --- type: reference +stage: Plan +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/#designated-technical-writers --- # Burndown Charts **(STARTER)** diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 085c1bd143e..421cb42de1e 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -1,5 +1,8 @@ --- type: index, reference +stage: Plan +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/#designated-technical-writers --- # Milestones diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 120c7a35cb2..cfcbf11a407 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,10 +1,17 @@ +--- +stage: Verify +group: Continuous Integration +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: reference +--- + # New CI job permissions model > Introduced in GitLab 8.12. GitLab 8.12 has a completely redesigned [job permissions](../permissions.md#job-permissions) system. You can find all discussion and all our concerns when choosing the current approach in issue -[#18994](https://gitlab.com/gitlab-org/gitlab-foss/issues/18994). +[#18994](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18994). Jobs permissions should be tightly integrated with the permissions of a user who is triggering a job. @@ -68,7 +75,7 @@ Let's consider the following scenario: A unique job token is generated for each job and provides the user read access all projects that would be normally accessible to the user creating that job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/issues/35067). +is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/-/issues/35067). We try to make sure that this token doesn't leak by: @@ -156,7 +163,7 @@ As an administrator: [check manually](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/update) for installations from source. - **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy, Apache, etc.). It might be a good idea to let GitLab use the internal NGINX - web server and not disable it completely. See [this comment](https://gitlab.com/gitlab-org/gitlab-foss/issues/22484#note_16648302) for an + web server and not disable it completely. See [this comment](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22484#note_16648302) for an example. - **403 errors**: You need to make sure that your installation has [HTTP(S) cloning enabled](../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols). HTTP(S) support is now a **requirement** by GitLab CI @@ -178,7 +185,7 @@ git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependent ``` It can also be used for system-wide authentication -(only do this in a docker container, it will overwrite ~/.netrc): +(only do this in a Docker container, it will overwrite ~/.netrc): ```shell echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 2dcf72aaf01..411b36411af 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: Health +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Alert Management > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. @@ -32,12 +38,14 @@ immediately identify which alerts you should prioritize investigating: Alerts contain one of the following icons: -- **Critical**: **{severity-critical}** and hexadecimal color `#8b2615` -- **High**: **{severity-high}** and hexadecimal color `#c0341d` -- **Medium**: **{severity-medium}** and hexadecimal color `#fca429` -- **Low**: **{severity-low}** and hexadecimal color `#fdbc60` -- **Info**: **{severity-info}** and hexadecimal color `#418cd8` -- **Unknown**: **{severity-unknown}** and hexadecimal color `#bababa` +| Severity | Icon | Color (hexadecimal) | +|---|---|---| +| Critical | **{severity-critical}** | `#8b2615` | +| High | **{severity-high}** | `#c0341d` | +| Medium | **{severity-medium}** | `#fca429` | +| Low | **{severity-low}** | `#fdbc60` | +| Info | **{severity-info}** | `#418cd8` | +| Unknown | **{severity-unknown}** | `#bababa` | ## Alert Management list @@ -72,8 +80,91 @@ You will need at least Developer [permissions](../../permissions.md) to view Ale Navigate to the Alert Management detail view by visiting the [Alert Management list](#alert-management-list) and selecting an Alert from the list. - + + + ### Update an Alert's status -The Alert Management detail view allows users to update the Alert Status. See [Alert Management statuses](#alert-management-statuses) for more details. +The Alert Management detail view enables you to update the Alert Status. +See [Alert Management statuses](#alert-management-statuses) for more details. + +### Create an Issue from an Alert + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1. + +The Alert Management detail view enables you to create an issue with a +description automatically populated from an alert. To create the issue, +click the **Create Issue** button. You can then view the issue from the +alert by clicking the **View Issue** button. + +Closing a GitLab issue associated with an alert changes the alert's status to Resolved. +See [Alert Management statuses](#alert-management-statuses) for more details about statuses. + +### Update an Alert's assignee + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. + +The Alert Management detail view allows users to update the Alert assignee. + +In large teams, where there is shared ownership of an alert, it can be difficult +to track who is investigating and working on it. The Alert Management detail view +enables you to update the Alert assignee: + +NOTE: **Note:** +GitLab currently only supports a single assignee per alert. + +1. To display the list of current alerts, click + **{cloud-gear}** **Operations > Alerts**: + +  + +1. Select your desired alert to display its **Alert Management Details View**: + +  + +1. If the right sidebar is not expanded, click + **{angle-double-right}** **Expand sidebar** to expand it. +1. In the right sidebar, locate the **Assignee** and click **Edit**. From the + dropdown menu, select each user you want to assign to the alert. GitLab creates + a [To-Do list item](../../todos.md) for each user. + +  + +To remove an assignee, click **Edit** next to the **Assignee** dropdown menu and +deselect the user from the list of assignees, or click **Unassigned**. + +### Alert system notes + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. + +NOTE: **Note:** +GitLab currently only supports creating system notes when assigning an Alert. + +Assigning a user an Alert creates a system note, visible in the Alert Details view, +giving you a linear timeline of the alert's investigation and assignment history. + + + +## Use cases for assigning alerts + +Consider a team formed by different sections of monitoring, collaborating on a +single application. After an alert surfaces, it's extremely important to +route the alert to the team members who can address and resolve the alert. + +Assigning Alerts to multiple assignees eases collaboration and delegation. All +assignees are shown in your team's work-flows, and all assignees receive +notifications, simplifying communication and ownership of the alert. + +After completing their portion of investigating or fixing the alert, users can +unassign their account from the alert when their role is complete. +The [alerts status](#alert-management-statuses) can be updated to +reflect if the alert has been resolved. + +### Slack Notifications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216326) in GitLab 13.1. + +You can be alerted via a Slack message when a new alert has been received. + +See the [Slack Notifications Service docs](../integrations/slack.md) for information on how to set this up. diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md new file mode 100644 index 00000000000..e14c478ab7a --- /dev/null +++ b/doc/user/project/operations/dashboard_settings.md @@ -0,0 +1,47 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Metrics dashboard settings + +You can configure your [Monitoring dashboard](../integrations/prometheus.md) to +display the time zone of your choice, and the links of your choice. + +## Change the dashboard time zone + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214370) in GitLab 13.1. + +By default, your monitoring dashboard displays dates and times in your local +time zone, but you can display dates and times in UTC format. To change the +time zone: + +1. Navigate to **{settings}** **Settings > Operations**, and scroll to + **Metrics Dashboard**. +1. In the **Dashboard timezone** select box, select *User's local timezone* + or *UTC*: + +  +1. Click **Save changes**. + +## Link to an external dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/57171) in GitLab 12.0. + +You can add a button on your monitoring dashboard that links directly to your +existing external dashboards: + +1. Navigate to **{settings}** **Settings > Operations**, and scroll to + **Metrics Dashboard**. +1. In **External dashboard URL**, provide the URL to your external dashboard: + +  + +1. Click **Save changes**. + +GitLab displays a **View full dashboard** button in the top right corner of your +[monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) +which opens the URL you provided: + + diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 23a50fd7766..a7a16de90e0 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -61,7 +61,7 @@ This page has: - A link to the Sentry issue. - A link to the GitLab commit if the Sentry [release ID/version](https://docs.sentry.io/workflow/releases/?platform=javascript#configure-sdk) on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project. - Other details about the issue, including a full stack trace. -- In [GitLab 12.7 and newer](https://gitlab.com/gitlab-org/gitlab/issues/36246), language and urgency are displayed. +- In [GitLab 12.7 and newer](https://gitlab.com/gitlab-org/gitlab/-/issues/36246), language and urgency are displayed. By default, a **Create issue** button is displayed: @@ -77,7 +77,7 @@ You can take action on Sentry Errors from within the GitLab UI. ### Ignoring errors -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/39665) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39665) in GitLab 12.7. From within the [Error Details](#error-details) page you can ignore a Sentry error by simply clicking the **Ignore** button near the top of the page. @@ -85,7 +85,7 @@ Ignoring an error will prevent it from appearing in the [Error Tracking List](#e ### Resolving errors -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/39825) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39825) in GitLab 12.7. From within the [Error Details](#error-details) page you can resolve a Sentry error by clicking the **Resolve** button near the top of the page. diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 8716d5feb4a..a9729204cd7 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -8,100 +8,73 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. -Feature flags allow you to ship a project in different flavors by -dynamically toggling certain functionality. +With Feature Flags, you can deploy your application's new features to production in smaller batches. +You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. +Feature flags help reduce risk, allowing you to do controlled testing, and separate feature +delivery from customer launch. -## Overview - -Feature Flags offer a feature toggle system for your application. They enable teams -to achieve Continuous Delivery by deploying new features to production at smaller -batches for controlled testing, separating feature delivery from customer launch. -This helps reducing risk and allows you to easily manage which features to enable. - -GitLab offers a Feature Flags interface that allows you to create, toggle and -remove feature flags. - -<div class="video-fallback"> - <a href="https://www.youtube.com/watch?v=5tw2p6lwXxo">Watch</a> a use case between Feature Flags and Sentry Error Tracking -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/5tw2p6lwXxo" frameborder="0" allowfullscreen="true"> </iframe> -</figure> +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo). ## How it works -Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature -toggle service. GitLab provides an API where your application can talk to and get the -list of feature flags you set in GitLab. +GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature +toggle service. -The application must be configured to talk to GitLab, so that's up to the -developers to use a compatible [client library](#client-libraries) and -integrate it in their app. +By enabling or disabling a flag in GitLab, your application +can determine which features to enable or disable. -By setting a flag active or inactive via GitLab, your application will automatically -know which features to enable or disable respectively. +You can create feature flags in GitLab and use the API from your application +to get the list of feature flags and their statuses. The application must be configured to communicate +with GitLab, so it's up to developers to use a compatible client library and +[integrate the feature flags in your app](#integrate-feature-flags-with-your-application). -## Adding a new feature flag +## Create a feature flag -To add a new feature flag: +To create and enable a feature flag: 1. Navigate to your project's **Operations > Feature Flags**. -1. Click on the **New Feature Flag** button. -1. Give it a name. - - NOTE: **Note:** - A name can contain only lowercase letters, digits, underscores (`_`) - and dashes (`-`), must start with a letter, and cannot end with a dash (`-`) - or an underscore (`_`). - -1. Give it a description (optional, 255 characters max). -1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs) +1. Click the **New feature flag** button. +1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`) + and dashes (`-`), and does not end with a dash (`-`) or underscore (`_`). +1. Enter a description (optional, 255 characters max). +1. Enter details about how the flag should be applied: + - In GitLab 13.0 and earlier: Enter an environment spec, + enable or disable the flag in this environment, and select a rollout strategy. + - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is enabled): Select a strategy and then + the environments to apply the strategy to. 1. Click **Create feature flag**. -Once a feature flag is created, the list of existing feature flags will be presented -with ability to edit or remove them. - -To make a feature flag active or inactive, click the pencil icon to edit it, -and toggle the status for each [spec](#define-environment-specs). +The feature flag is displayed in the list. It is enabled by default. -The toggles next to each feature flag on the list page function as global shutoff switches. -If a toggle is off, that feature flag is disabled for every environment. +## Disable a feature flag for a specific environment - +In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621), +to disable a feature flag for a specific environment: -## Define environment specs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8621) in GitLab 11.8. - -In general, an application is deployed to multiple environments, such as -production, staging and [review apps](../../../ci/review_apps/index.md). -For example, you may not want to enable a feature flag on production until your QA team has -first confirmed that the feature is working correctly on testing environments. +1. Navigate to your project's **Operations > Feature Flags**. +1. For the feature flag you want to disable, click the Pencil icon. +1. To disable the flag: + - In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the + environment spec, on the right, click the **Remove (X)** icon. + - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is + enabled): For each strategy it applies to, under **Environments**, delete the environment. +1. Click **Save changes**. -To handle these situations, you can enable a feature flag on a particular environment -with [Environment specs](../../../ci/environments/index.md#scoping-environments-with-specs). -You can define multiple specs per flag so that you can control your feature flag more granularly. +## Disable a feature flag for all environments -To define specs for each environment: +To disable a feature flag for all environments: 1. Navigate to your project's **Operations > Feature Flags**. -1. Click on the **New Feature Flag** button or edit an existing flag. -1. Set the status of the default [spec](../../../ci/environments/index.md#scoping-environments-with-specs) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments. -1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments/index.md#scoping-environments-with-specs) and type the environment name. -1. Set the status and rollout strategy of the additional spec. This status and rollout strategy combination takes precedence over the default spec since we always use the most specific match available. -1. Click **Create feature flag** or **Update feature flag**. +1. For the feature flag you want to disable, slide the Status toggle to **Disabled**. - - -NOTE: **NOTE** -We'd highly recommend you to use the [Environment](../../../ci/environments/index.md) -feature in order to quickly assess which flag is enabled per environment. +The feature flag is displayed on the **Disabled** tab. ## Feature flag behavior change in 13.0 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0. -Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environment specs, +Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environments, without defining the strategy multiple times. This feature is under development and not ready for production use. It is @@ -121,29 +94,18 @@ To disable it: Feature.disable(:feature_flags_new_version) ``` -### Applying a strategy to environments - -After a strategy is defined, it applies to **All Environments** by default. To -make a strategy apply to a specific environment spec: +## Feature flag strategies -1. Click the **Add Environment** button. -1. Create a new - [spec](../../../ci/environments/index.md#scoping-environments-with-specs). - -To apply the strategy to multiple environment specs, repeat these steps. - -## Feature Flag strategies - -GitLab Feature Flag adopts [Unleash](https://unleash.github.io) -as the feature flag engine. In unleash, there is a concept of rulesets for granular feature flag controls, +GitLab Feature Flag uses [Unleash](https://unleash.github.io) +as the feature flag engine. In Unleash, there is a concept of rulesets for granular feature flag controls, called [strategies](https://unleash.github.io/docs/activation_strategy). Supported strategies for GitLab Feature Flags are described below. ### Rollout strategy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. -The selected rollout strategy affects which users will experience the feature enabled. +The selected rollout strategy affects which users will experience the feature as enabled. The status of an environment spec ultimately determines whether or not a feature is enabled at all. For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy. @@ -172,36 +134,34 @@ ID for the feature to be enabled. See the [Ruby example](#ruby-application-examp #### User IDs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/issues/34363) to be defined per environment in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6. A feature flag may be enabled for a list of target users. It is implemented using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid) activation strategy. -User IDs should be a comma separated list of values. For example, `user@example.com, user2@example.com`, or `username1,username2,username3`, etc. +User IDs should be a comma-separated list of values. For example, `user@example.com, user2@example.com`, or `username1,username2,username3`, etc. CAUTION: **Caution:** The Unleash client **must** be given a user ID for the feature to be enabled for target users. See the [Ruby example](#ruby-application-example) below. -## Integrating with your application +## Integrate feature flags with your application -In order to use Feature Flags, you need to first -[get the access credentials](#configuring-feature-flags) from GitLab and then -prepare your application and hook it with a [client library](#client-libraries). +To use feature flags with your application, get access credentials from GitLab. +Then prepare your application with a client library. -## Configuring Feature Flags +### Get access credentials -To get the access credentials that your application will need to talk to GitLab: +To get the access credentials that your application needs to communicate with GitLab: 1. Navigate to your project's **Operations > Feature Flags**. -1. Click on the **Configure** button to see the values: +1. Click the **Configure** button to view the following: - **API URL**: URL where the client (application) connects to get a list of feature flags. - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. - **Application name**: The name of the running environment. For instance, - if the application runs for a production server, application name would be - `production` or similar. This value is used for - [the environment spec evaluation](#define-environment-specs). + if the application runs for a production server, the application name would be + `production` or similar. This value is used for the environment spec evaluation. NOTE: **Note:** The meaning of these fields might change over time. For example, we are not sure @@ -209,34 +169,28 @@ if **Instance ID** will be single token or multiple tokens, assigned to the **Environment**. Also, **Application name** could describe the version of application instead of the running environment. -## Client libraries +### Choose a client library -GitLab currently implements a single backend that is compatible with -[Unleash](https://github.com/Unleash/unleash#client-implementations) clients. +GitLab implements a single backend that is compatible with Unleash clients. -Unleash clients allow the developers to define in the app's code the default -values for flags. Each feature flag evaluation can express the desired -outcome in case the flag isn't present on the provided configuration file. +With the Unleash client, developers can define, in the application code, the default values for flags. +Each feature flag evaluation can express the desired outcome if the flag isn't present in the +provided configuration file. -Unleash currently offers a number of official SDKs for various frameworks and -a number of community contributed libraries. +Unleash currently [offers many SDKs for various languages and frameworks](https://github.com/Unleash/unleash#client-implementations). -Official clients: +### Feature flags API information -- [Unleash client SDK for Java](https://github.com/unleash/unleash-client-java) -- [Unleash client SDK for Node.js](https://github.com/unleash/unleash-client-node) -- [Unleash client for Go](https://github.com/unleash/unleash-client-go) -- [Unleash client for Ruby](https://github.com/unleash/unleash-client-ruby) +For API content, see: -Community contributed clients: - -- [Unleash FeatureToggle Client for .Net](https://github.com/stiano/unleash-client-dotnet) -- [Unofficial .Net Core Unleash client](https://github.com/onybo/unleash-client-core) -- [Unleash client for Python 3](https://github.com/aes/unleash-client-python) +- [Feature Flags API](../../../api/feature_flags.md) +- [Feature Flag Specs API](../../../api/feature_flag_specs.md) (Deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).) +- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md) +- [Legacy Feature Flags API](../../../api/feature_flags_legacy.md) -## Golang application example +### Golang application example -Here's an example of how to integrate the feature flags in a Golang application: +Here's an example of how to integrate feature flags in a Golang application: ```golang package main @@ -275,9 +229,9 @@ func main() { } ``` -## Ruby application example +### Ruby application example -Here's an example of how to integrate the feature flags in a Ruby application. +Here's an example of how to integrate feature flags in a Ruby application. The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. @@ -305,12 +259,3 @@ else puts "hello, world!" end ``` - -## Feature Flags API - -You can create, update, read, and delete Feature Flags via API -to control them in an automated flow: - -- [Feature Flags API](../../../api/feature_flags.md) -- [Feature Flag Specs API](../../../api/feature_flag_specs.md) -- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md) diff --git a/doc/user/project/operations/img/alert_detail_full_v13_1.png b/doc/user/project/operations/img/alert_detail_full_v13_1.png Binary files differnew file mode 100644 index 00000000000..18a6f4fb67b --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_full_v13_1.png diff --git a/doc/user/project/operations/img/alert_detail_overview_v13_1.png b/doc/user/project/operations/img/alert_detail_overview_v13_1.png Binary files differnew file mode 100644 index 00000000000..10c945d3810 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_overview_v13_1.png diff --git a/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png b/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png Binary files differnew file mode 100644 index 00000000000..2a6d0320a54 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_system_notes_v13_1.png diff --git a/doc/user/project/operations/img/alert_detail_v13_0.png b/doc/user/project/operations/img/alert_detail_v13_0.png Binary files differdeleted file mode 100644 index 7da09407cd5..00000000000 --- a/doc/user/project/operations/img/alert_detail_v13_0.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_details_assignees_v13_1.png b/doc/user/project/operations/img/alert_details_assignees_v13_1.png Binary files differnew file mode 100644 index 00000000000..dab4eac384a --- /dev/null +++ b/doc/user/project/operations/img/alert_details_assignees_v13_1.png diff --git a/doc/user/project/operations/img/alert_issue_v13_1.png b/doc/user/project/operations/img/alert_issue_v13_1.png Binary files differnew file mode 100644 index 00000000000..da79074aa2f --- /dev/null +++ b/doc/user/project/operations/img/alert_issue_v13_1.png diff --git a/doc/user/project/operations/img/alert_list_assignees_v13_1.png b/doc/user/project/operations/img/alert_list_assignees_v13_1.png Binary files differnew file mode 100644 index 00000000000..db1e0d8dcb7 --- /dev/null +++ b/doc/user/project/operations/img/alert_list_assignees_v13_1.png diff --git a/doc/user/project/operations/img/alert_management_1_v13_1.png b/doc/user/project/operations/img/alert_management_1_v13_1.png Binary files differindex c01b4749eda..00aa56a6050 100644 --- a/doc/user/project/operations/img/alert_management_1_v13_1.png +++ b/doc/user/project/operations/img/alert_management_1_v13_1.png diff --git a/doc/user/project/operations/img/alert_todo_assignees_v13_1.png b/doc/user/project/operations/img/alert_todo_assignees_v13_1.png Binary files differnew file mode 100644 index 00000000000..637f8be5d25 --- /dev/null +++ b/doc/user/project/operations/img/alert_todo_assignees_v13_1.png diff --git a/doc/user/project/operations/img/dashboard_external_link_v13_1.png b/doc/user/project/operations/img/dashboard_external_link_v13_1.png Binary files differnew file mode 100644 index 00000000000..3e8d792c53e --- /dev/null +++ b/doc/user/project/operations/img/dashboard_external_link_v13_1.png diff --git a/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png b/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png Binary files differnew file mode 100644 index 00000000000..8d45607a940 --- /dev/null +++ b/doc/user/project/operations/img/dashboard_local_timezone_v13_1.png diff --git a/doc/user/project/operations/img/external_dashboard_settings.png b/doc/user/project/operations/img/external_dashboard_settings.png Binary files differdeleted file mode 100644 index e1b7fa56a1c..00000000000 --- a/doc/user/project/operations/img/external_dashboard_settings.png +++ /dev/null diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index 954f88fe4f2..ca38eab9455 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -10,4 +10,4 @@ your applications: - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). - Create, toggle, and remove [Feature Flags](feature_flags.md). **(PREMIUM)** - [Trace](tracing.md) the performance and health of a deployed application. **(ULTIMATE)** -- Add a [button to the Monitoring dashboard](linking_to_an_external_dashboard.md) linking directly to your existing external dashboards. +- Change the [settings of the Monitoring Dashboard](dashboard_settings.md). diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index 8e1117de4c7..ff609a3720e 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -1,19 +1,5 @@ -# Linking to an external dashboard +--- +redirect_to: 'dashboard_settings.md' +--- -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/57171) in GitLab 12.0. - -You can add a button to the Monitoring dashboard linking directly to your existing external dashboards. - -## Enabling the external dashboard link - -1. Go to **Settings > Operations** and scroll to the section titled **External dashboard**. - -1. Fill in the URL to your external dashboard and click **Save changes**. - -  - -1. There should now be a button on your - [Monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) which - will open the URL you entered in the above step. - -  +This document was moved to [another location](dashboard_settings.md). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index a5fc5b00b53..bf9b58acf14 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -273,7 +273,7 @@ Sublime Text, Atom, Dreamweaver, Brackets, etc). ## Force HTTPS for GitLab Pages websites -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28857) in GitLab 10.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28857) in GitLab 10.7. To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your @@ -287,6 +287,9 @@ To enable this setting: 1. Navigate to your project's **Settings > Pages**. 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. +NOTE: **Note** +If you use CloudFlare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [CloudFlare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 8b180d438ef..4b4b430b663 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages integration with Let's Encrypt -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains @@ -19,7 +19,7 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. CAUTION: **Caution:** -This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index 00cea846f91..de9bd97b262 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -5,68 +5,52 @@ group: Release 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/#designated-technical-writers --- -# New Pages website from a forked sample - -To get started with GitLab Pages from a sample website, the easiest -way to do it is by using one of the [bundled templates](pages_bundled_template.md). -If you don't find one that suits your needs, you can opt by -forking (copying) a [sample project from the most popular Static Site Generators](https://gitlab.com/pages). - -<table class="borderless-table center fixed-table middle width-80"> - <tr> - <td style="width: 30%"><img src="../img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="../img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="../img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Fork an example project</em></td> - <td></td> - <td><em>Deploy your website</em></td> - <td></td> - <td><em>Visit your website's URL</em></td> - </tr> -</table> - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** - -1. [Fork](../../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. Once the pipeline has finished successfully, find the link to visit your - website from your project's **Settings > Pages**. It can take approximately - 30 minutes to be deployed. - -You can also take some **optional** further steps: - -- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: - -  - -- _Make it a user or group website._ To turn a **project website** forked - from the Pages group into a **user/group** website, you'll need to: - - Rename it to `namespace.gitlab.io`: go to your project's - **Settings > General** and expand **Advanced**. Scroll down to - **Change path** and change the path to `namespace.gitlab.io`. - - For example, consider the group `https://gitlab.com/gitlab-tests`: - `gitlab-tests` is the group's namespace, the repository path should be set - to `gitlab-tests.gitlab.io` (yes, weird like that), and the - resulting URL for your Pages website will be `https://gitlab-tests.gitlab.io`. +# Create a Pages website from a forked sample + +GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). +You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. + +Fork a sample project when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) of how this works. + +To fork a sample project and create a Pages website: + +1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. +1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). +1. In the top right, click the **Fork** button, and then choose a namespace to fork to. +1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. + GitLab CI/CD builds and deploys your site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. + +You can take some **optional** further steps: + +- _Remove the fork relationship._ If you want to contribute to the project you forked from, + you can keep this relationship. Otherwise, go to your project's **Settings > General**, + expand **Advanced settings**, and scroll down to **Remove fork relationship**: + +  + +- _Change the URL to match your namespace._ If your Pages site is hosted on GitLab.com, + you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace + (the one you chose when you forked the project). + + - Go to your project's **Settings > General** and expand **Advanced**. Scroll down to + **Change path** and change the path to `<namespace>.gitlab.io`. + + For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is + `gitlab-tests`. + + If you set the repository path to `gitlab-tests.gitlab.io`, + the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`.  - - Adjust your SSG's [base URL](../getting_started_part_one.md#urls-and-baseurls) from `"project-name"` to - `""`. This setting will be at a different place for each SSG, as each of them - have their own structure and file tree. Most likely, it will be in the SSG's - config file. + - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) + from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the config file. diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index 9a00b724753..5d7126ab22e 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -5,44 +5,45 @@ group: Release 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/#designated-technical-writers --- -# Start a new Pages website from scratch or deploy an existing website +# Create a Pages website by using a CI/CD template -If you already have a website and want to deploy it with GitLab Pages, -or, if you want to start a new site from scratch, you'll need to: +GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). +You can create your own `.gitlab-ci.yml` file from one of these templates, and run +the CI/CD pipeline to generate a Pages website. -- Create a new project in GitLab to hold your site content. -- Set up GitLab CI/CD to deploy your website to Pages. +Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to. -To do so, follow the steps below. +Your GitLab repository should contain files specific to an SSG, or plain HTML. +After you complete these steps, you may need to do additional +configuration for the Pages site to generate properly. -1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, - click **New project**, and name it according to the - [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names). -1. Clone it to your local computer, add your website - files to your project, add, commit, and push to GitLab. - Alternatively, you can run `git init` in your local directory, - add the remote URL: - `git remote add origin git@gitlab.com:namespace/project-name.git`, - then add, commit, and push to GitLab. -1. From the your **Project**'s page, click **Set up CI/CD**: +1. In the left sidebar, click **Project overview**. +1. Click **Set up CI/CD**. -  +  -1. Choose one of the templates from the dropbox menu. - Pick up the template corresponding to the SSG you're using (or plain HTML). + If this button is not available, CI/CD is already configured for + your project. You may want to browse the `.gitlab-ci.yml` files + [in these projects instead](https://gitlab.com/pages). -  +1. From the **Apply a template** list, choose a template for the SSG you're using. + You can also choose plain HTML. - Note that, if you don't find a corresponding template, you can look into - [GitLab Pages group of sample projects](https://gitlab.com/pages), - you may find one among them that suits your needs, from which you - can copy `.gitlab-ci.yml`'s content and adjust for your case. - If you don't find it there either, [learn how to write a `.gitlab-ci.yml` +  + + If you don't find a corresponding template, you can view the + [GitLab Pages group of sample projects](https://gitlab.com/pages). + These projects contain `.gitlab-ci.yml` files that you can modify for your needs. + You can also [learn how to write your own `.gitlab-ci.yml` file for GitLab Pages](../getting_started_part_four.md). -Once you have both site files and `.gitlab-ci.yml` in your project's -root, GitLab CI/CD will build your site and deploy it with Pages. -Once the first build passes, you access your site by -navigating to your **Project**'s **Settings** > **Pages**, -where you'll find its default URL. It can take approximately 30 min to be -deployed. +1. Save and commit the `.gitlab-ci.yml` file. + +If everything is configured correctly, the site can take approximately 30 minutes to deploy. + +You can watch the pipeline run by going to **CI / CD > Pipelines**. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index 745c50e8d65..cfa4e0910db 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -5,27 +5,30 @@ group: Release 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/#designated-technical-writers --- -# New Pages website from a bundled template +# Create a Pages website from a new project template -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) in GitLab 11.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. -The simplest way to create a GitLab Pages site is to use one of the most -popular templates, which come already bundled with GitLab and are ready to go. +GitLab provides templates for the most popular Static Site Generators (SSGs). +You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. + +Use a template when you want to test GitLab Pages or start a new project that's already +configured to generate a Pages site. 1. From the top navigation, click the **+** button and select **New project**. 1. Select **Create from Template**. -1. Choose one of the templates starting with **Pages**: +1. Next to one of the templates starting with **Pages**, click **Use template**. -  +  +1. Complete the form and click **Create project**. 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. After the pipeline has finished successfully, wait approximately 30 minutes - for your website to be visible. After waiting 30 minutes, find the link to - visit your website from your project's **Settings > Pages**. If the link - leads to a 404 page, wait a few minutes and try again. - -Your website is then visible on your domain and you can modify your files -as you wish. For every modification pushed to your repository, GitLab CI/CD -will run a new pipeline to immediately publish your changes to the server. + site. + +The site can take approximately 30 minutes to deploy. +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. + +For every change pushed to your repository, GitLab CI/CD runs a new pipeline +that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 4e95b5d5a69..8cf58280b88 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -6,137 +6,146 @@ group: Release 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/#designated-technical-writers --- -# Creating and Tweaking GitLab CI/CD for GitLab Pages - -To [get started with GitLab Pages](index.md#getting-started), you can -use one of the project templates, a `.gitlab-ci.yml` template, -or fork an existing example project. Therefore, you don't need to -understand _all_ the ins and odds of GitLab CI/CD to get your site -deployed. Still, there are cases where you want to write your own -script or tweak an existing one. This document guides you through -this process. - -This guide also provides a general overview and clear introduction -for **getting familiar with the `.gitlab-ci.yml` file and writing -one for the first time.** - -[GitLab CI/CD](../../../ci/README.md) serves -numerous purposes, to build, test, and deploy your app -from GitLab through -[Continuous Integration, Continuous Delivery, and Continuous Deployment](../../../ci/introduction/index.md#introduction-to-cicd-methodologies) -methods. You will need it to build your website with GitLab Pages, -and deploy it to the Pages server. - -To implement GitLab CI/CD, the first thing you need is a configuration -file called `.gitlab-ci.yml` placed at your website's root directory. - -What this file actually does is telling the -[GitLab Runner](https://docs.gitlab.com/runner/) to run scripts -as you would do from the command line. The Runner acts as your -terminal. GitLab CI/CD tells the Runner which commands to run. -Both are built-in in GitLab, and you don't need to set up -anything for them to work. - -Explaining [every detail of GitLab CI/CD](../../../ci/yaml/README.md) -and GitLab Runner is out of the scope of this guide, but we'll -need to understand just a few things to be able to write our own -`.gitlab-ci.yml` or tweak an existing one. It's a -[YAML](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) file, -with its own syntax. You can always check your CI syntax with -the [GitLab CI/CD Lint Tool](https://gitlab.com/ci/lint). - -## Practical example - -Let's consider you have a [Jekyll](https://jekyllrb.com/) site. -To build it locally, you would open your terminal, and run `jekyll build`. -Of course, before building it, you had to install Jekyll in your computer. -For that, you had to open your terminal and run `gem install jekyll`. -Right? GitLab CI/CD + GitLab Runner do the same thing. But you need to -write in the `.gitlab-ci.yml` the script you want to run so -GitLab Runner will do it for you. It looks more complicated than it -is. What you need to tell the Runner: - -```shell -gem install jekyll -jekyll build +# Create a GitLab Pages website from scratch + +This tutorial shows you how to create a Pages site from scratch. You will start with +a blank project and create your own CI file, which gives instruction to the +[GitLab 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 +to complete this tutorial. + +## Prerequisites + +To follow along with this example, start with a blank project in GitLab. +Create three files in the root (top-level) directory. + +- `.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. + Populate it with this content: + + ```ruby + source "https://rubygems.org" + + gem "jekyll" + ``` + +## Choose a Docker image + +In this example, the Runner uses a [Docker image](../../../ci/docker/using_docker_images.md) +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. + +```yaml +image: ruby:2.7 ``` -### Script +If your SSG needs [NodeJS](https://nodejs.org/) to build, you must specify an +image that contains NodeJS as part of its file system. For example, for a +[Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:12.17.0`. + +## Install Jekyll + +To run [Jekyll](https://jekyllrb.com/) locally, you would open your terminal and: -To transpose this script to YAML, it would be like this: +- 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`. + +In the `.gitlab-ci.yml` file, this is written as: ```yaml script: - - gem install jekyll - - jekyll build + - gem install bundler + - bundle install + - bundle exec jekyll build ``` -### Job - -So far so good. Now, each `script`, in GitLab is organized by -a `job`, which is a bunch of scripts and settings you want to -apply to that specific task. +In addition, in the `.gitlab-ci.yml` file, each `script` is organized by a `job`. +A `job` includes the scripts and settings you want to apply to that specific +task. ```yaml job: script: - - gem install jekyll - - jekyll build + - gem install bundler + - bundle install + - bundle exec jekyll build ``` -For GitLab Pages, this `job` has a specific name, called `pages`, -which tells the Runner you want that task to deploy your website +For GitLab Pages, this `job` has a specific name, called `pages`. +This setting tells the Runner you want the job to deploy your website with GitLab Pages: ```yaml pages: script: - - gem install jekyll - - jekyll build + - gem install bundler + - bundle install + - bundle exec jekyll build ``` -### The `public` directory +## Specify the `public` directory for output + +Jekyll needs to know where to generate its output. +GitLab Pages only considers files in a directory called `public`. -We also need to tell Jekyll where do you want the website to build, -and GitLab Pages will only consider files in a directory called `public`. -To do that with Jekyll, we need to add a flag specifying the -[destination (`-d`)](https://jekyllrb.com/docs/usage/) of the -built website: `jekyll build -d public`. Of course, we need -to tell this to our Runner: +Jekyll uses destination (`-d`) to specify an output directory for the built website: ```yaml pages: script: - - gem install jekyll - - jekyll build -d public + - gem install bundler + - bundle install + - bundle exec jekyll build -d public ``` -### Artifacts +## Specify the `public` directory for artifacts -We also need to tell the Runner that this _job_ generates -_artifacts_, which is the site built by Jekyll. -Where are these artifacts stored? In the `public` directory: +Now that Jekyll has output the files to the `public` directory, +the Runner needs to know where to get them. The artifacts are stored +in the `public` directory: ```yaml pages: script: - - gem install jekyll - - jekyll build -d public + - gem install bundler + - bundle install + - bundle exec jekyll build -d public artifacts: paths: - public ``` -The script above would be enough to build your Jekyll -site with GitLab Pages. But, from Jekyll 3.4.0 on, its default -template originated by `jekyll new project` requires -[Bundler](https://bundler.io) to install Jekyll dependencies -and the default theme. To adjust our script to meet these new -requirements, we only need to install and build Jekyll with Bundler: +Paste this into `.gitlab-ci.yml` file, so it now looks like this: ```yaml +image: ruby:2.7 + pages: script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: @@ -144,27 +153,35 @@ pages: - public ``` -That's it! A `.gitlab-ci.yml` with the content above would deploy -your Jekyll 3.4.0 site with GitLab Pages. This is the minimum -configuration for our example. On the steps below, we'll refine -the script by adding extra options to our GitLab CI/CD. +Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run +by going to **CI / CD > Pipelines**. + +When it succeeds, go to **Settings > Pages** to view the URL where your site +is now available. + +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 check +your CI syntax with the [GitLab CI/CD Lint Tool](https://gitlab.com/ci/lint). + +The following topics show other examples of other options you can add to your CI/CD file. -Artifacts will be automatically deleted once GitLab Pages got deployed. -You can preserve artifacts for limited time by specifying the expiry time. +## Deploy specific branches to a Pages site -### Image +You may want to deploy to a Pages site only from specific branches. -At this point, you probably ask yourself: "okay, but to install Jekyll -I need Ruby. Where is Ruby on that script?". The answer is simple: the -first thing GitLab Runner will look for in your `.gitlab-ci.yml` is a -[Docker](https://www.docker.com/) image specifying what do you need in -your container to run that script: +First, add a `workflow` section to force the pipeline to run only when changes are +pushed to branches: ```yaml image: ruby:2.7 +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' + pages: script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: @@ -172,134 +189,122 @@ pages: - public ``` -In this case, you're telling the Runner to pull this image, which -contains Ruby 2.7 as part of its file system. When you don't specify -this image in your configuration, the Runner will use a default -image, which is Ruby 2.6. - -If your SSG needs [NodeJS](https://nodejs.org/) to build, you'll -need to specify which image you want to use, and this image should -contain NodeJS as part of its file system. E.g., for a -[Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:4.2.2`. - ->**Note:** -We're not trying to explain what a Docker image is, -we just need to introduce the concept with a minimum viable -explanation. To know more about Docker images, please visit -their website or take a look at a -[summarized explanation](http://paislee.io/how-to-automate-docker-deployments/) here. - -Let's go a little further. - -### Branching - -If you use GitLab as a version control platform, you will have your -branching strategy to work on your project. Meaning, you will have -other branches in your project, but you'll want only pushes to the -default branch (usually `master`) to be deployed to your website. -To do that, we need to add another line to our CI, telling the Runner -to only perform that _job_ called `pages` on the `master` branch `only`: +Then configure the pipeline to run the job for the master branch only. ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' pages: script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' ``` -### Stages +## Specify a stage to deploy -Another interesting concept to keep in mind are build stages. -Your web app can pass through a lot of tests and other tasks -until it's deployed to staging or production environments. -There are three default stages on GitLab CI/CD: build, test, -and deploy. To specify which stage your _job_ is running, -simply add another line to your CI: +There are three default stages for GitLab CI/CD: build, test, +and deploy. + +If you want to test your script and check the built site before deploying +to production, you can run the test exactly as it will run when you +push to `master`. + +To specify a stage for your job to run in, +add a `stage` line to your CI file: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' pages: stage: deploy script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' ``` -You might ask yourself: "why should I bother with stages -at all?" Well, let's say you want to be able to test your -script and check the built site before deploying your site -to production. You want to run the test exactly as your -script will do when you push to `master`. It's simple, -let's add another task (_job_) to our CI, telling it to -test every push to other branches, `except` the `master` branch: +Now add another job to the CI file, telling it to +test every push to every branch **except** the `master` branch: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' pages: stage: deploy script: + - gem install bundler - bundle install - bundle exec jekyll build -d public artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' test: stage: test script: + - gem install bundler - bundle install - bundle exec jekyll build -d test artifacts: paths: - test - except: - - master + rules: + - if: '$CI_COMMIT_BRANCH != "master"' ``` -The `test` job is running on the stage `test`, Jekyll -will build the site in a directory called `test`, and -this job will affect all the branches except `master`. - -The best benefit of applying _stages_ to different -_jobs_ is that every job in the same stage builds in -parallel. So, if your web app needs more than one test -before being deployed, you can run all your test at the -same time, it's not necessary to wait one test to finish -to run the other. Of course, this is just a brief -introduction of GitLab CI/CD and GitLab Runner, which are -tools much more powerful than that. This is what you -need to be able to create and tweak your builds for -your GitLab Pages site. - -### Before Script - -To avoid running the same script multiple times across -your _jobs_, you can add the parameter `before_script`, -in which you specify which commands you want to run for -every single _job_. In our example, notice that we run -`bundle install` for both jobs, `pages` and `test`. -We don't need to repeat it: +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`. + +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 + +To avoid duplicating the same scripts in every job, you can add them +to a `before_script` section. + +In the example, `gem install bundler` and `bundle install` were running +for both jobs, `pages` and `test`. + +Move these commands to a `before_script` section: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' before_script: + - gem install bundler - bundle install pages: @@ -309,8 +314,8 @@ pages: artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' test: stage: test @@ -319,26 +324,31 @@ test: artifacts: paths: - test - except: - - master + rules: + - if: '$CI_COMMIT_BRANCH != "master"' ``` -### Caching 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. -If you want to cache the installation files for your -projects dependencies, for building faster, you can -use the parameter `cache`. For this example, we'll -cache Jekyll dependencies in a `vendor` directory -when we run `bundle install`: +This example caches Jekyll dependencies in a `vendor` directory +when you run `bundle install`: ```yaml -image: ruby:2.6 +image: ruby:2.7 + +workflow: + rules: + - if: '$CI_COMMIT_BRANCH' cache: paths: - vendor/ before_script: + - gem install bundler - bundle install --path vendor pages: @@ -348,8 +358,8 @@ pages: artifacts: paths: - public - only: - - master + rules: + - if: '$CI_COMMIT_BRANCH == "master"' test: stage: test @@ -358,40 +368,35 @@ test: artifacts: paths: - test - except: - - master + rules: + - if: '$CI_COMMIT_BRANCH != "master"' ``` -For this specific case, we need to exclude `/vendor` -from Jekyll `_config.yml` file, otherwise Jekyll will -understand it as a regular directory to build -together with the site: +In this case, you need to exclude the `/vendor` +directory from the list of folders Jekyll builds. Otherwise, Jekyll +will try to build the directory contents along with the site. + +In the root directory, create a file called `_config.yml` +and add this content: ```yaml exclude: - vendor ``` -There we go! Now our GitLab CI/CD not only builds our website, -but also **continuously test** pushes to feature-branches, +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 deploy** every push to the `master` branch. +**continuously deploys** every push to the `master` branch. -## Advanced GitLab CI for GitLab Pages +## Related topics -What you can do with GitLab CI/CD is pretty much up to your -creativity. Once you get used to it, you start creating -awesome scripts that automate most of tasks you'd do -manually in the past. Read through the -[documentation of GitLab CI/CD](../../../ci/yaml/README.md) -to understand how to go even further on your scripts. +For more information, see the following blog posts. -- On this blog post, understand the concept of - [using GitLab CI/CD `environments` to deploy your +- [Use GitLab CI/CD `environments` to deploy your web app to staging and production](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/). -- On this post, learn [how to run jobs sequentially, - in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/) -- On this blog post, we go through the process of - [pulling specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) - to deploy this website you're looking at, <https://docs.gitlab.com>. -- On this blog post, we teach you [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). +- Learn [how to run jobs sequentially, + in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). +- Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + to deploy this website, <https://docs.gitlab.com>. +- Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). diff --git a/doc/user/project/pages/img/change_path_v12_10.png b/doc/user/project/pages/img/change_path_v12_10.png Binary files differindex 7ca09bd21a3..9b5c17f1dda 100644 --- a/doc/user/project/pages/img/change_path_v12_10.png +++ b/doc/user/project/pages/img/change_path_v12_10.png diff --git a/doc/user/project/pages/img/choose_ci_template.png b/doc/user/project/pages/img/choose_ci_template.png Binary files differdeleted file mode 100644 index 0697542abc8..00000000000 --- a/doc/user/project/pages/img/choose_ci_template.png +++ /dev/null diff --git a/doc/user/project/pages/img/choose_ci_template_v13_1.png b/doc/user/project/pages/img/choose_ci_template_v13_1.png Binary files differnew file mode 100644 index 00000000000..84dd9fe2e0f --- /dev/null +++ b/doc/user/project/pages/img/choose_ci_template_v13_1.png diff --git a/doc/user/project/pages/img/pages_project_templates_v11_8.png b/doc/user/project/pages/img/pages_project_templates_v11_8.png Binary files differdeleted file mode 100644 index 61cae88b5a8..00000000000 --- a/doc/user/project/pages/img/pages_project_templates_v11_8.png +++ /dev/null diff --git a/doc/user/project/pages/img/pages_project_templates_v13_1.png b/doc/user/project/pages/img/pages_project_templates_v13_1.png Binary files differnew file mode 100644 index 00000000000..3f6d1ecd786 --- /dev/null +++ b/doc/user/project/pages/img/pages_project_templates_v13_1.png diff --git a/doc/user/project/pages/img/remove_fork_relationship.png b/doc/user/project/pages/img/remove_fork_relationship.png Binary files differdeleted file mode 100644 index 67c45491f08..00000000000 --- a/doc/user/project/pages/img/remove_fork_relationship.png +++ /dev/null diff --git a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png Binary files differnew file mode 100644 index 00000000000..1bc7bcd253b --- /dev/null +++ b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png diff --git a/doc/user/project/pages/img/setup_ci.png b/doc/user/project/pages/img/setup_ci.png Binary files differdeleted file mode 100644 index 214c1cc668f..00000000000 --- a/doc/user/project/pages/img/setup_ci.png +++ /dev/null diff --git a/doc/user/project/pages/img/setup_ci_v13_1.png b/doc/user/project/pages/img/setup_ci_v13_1.png Binary files differnew file mode 100644 index 00000000000..2cf1c05d6d8 --- /dev/null +++ b/doc/user/project/pages/img/setup_ci_v13_1.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index e81c9699153..5861282ca6f 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,7 +1,5 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' -last_updated: 2019-06-04 -type: index, reference stage: Release group: Release 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/#designated-technical-writers @@ -11,46 +9,76 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80) in GitLab Enterprise Edition 8.3. > - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173) in GitLab Enterprise Edition 8.5. -> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/issues/14605) to GitLab Community Edition in GitLab 8.17. -> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30548) in GitLab 11.8. -> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) in GitLab 11.8. +> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14605) to GitLab Community Edition in GitLab 8.17. +> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30548) in GitLab 11.8. +> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. -**GitLab Pages is a feature that allows you to publish static websites -directly from a repository in GitLab.** - -You can use it either for personal or business websites, such as -portfolios, documentation, manifestos, and business presentations. -You can also attribute any license to your content. - -<img src="img/pages_workflow_v12_5.png" alt="Pages websites workflow" class="image-noshadow"> - -Pages is available for free for all GitLab.com users as well as for self-managed -instances (GitLab Core, Starter, Premium, and Ultimate). - -## Overview +With GitLab Pages, you can publish static websites +directly from a repository in GitLab. <div class="row"> <div class="col-md-9"> <p style="margin-top: 18px;"> -To publish a website with Pages, you can use any Static Site Generator (SSG), -such as Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also -publish any website written directly in plain HTML, CSS, and JavaScript.</p> -<p>Pages does <strong>not</strong> support dynamic server-side processing, for instance, as <code>.php</code> and <code>.asp</code> requires. See this article to learn more about -<a href="https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p> +<ul> +<li>Use for any personal or business website.</li> +<li>Use any Static Site Generator (SSG) or plain HTML.</li> +<li>Create websites for your projects, groups, or user account.</li> +<li>Host your site on your own GitLab instance or on GitLab.com for free.</li> +<li>Connect your custom domains and TLS certificates.</li> +<li>Attribute any license to your content.</li> +</ul> +</p> </div> <div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> </div> -### How it works +To publish a website with Pages, you can use any SSG, +like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also +publish any website written directly in plain HTML, CSS, and JavaScript. -To use GitLab Pages, first you need to create a project in GitLab to upload your website's -files to. These projects can be either public, internal, or private, at your own choice. +Pages does **not** support dynamic server-side processing, for instance, as `.php` and `.asp` requires. +Learn more about +[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). + +## Getting started + +To create a GitLab Pages website: + +| Document | Description | +| -------- | ----------- | +| [Use a `.gitlab-ci.yml` template](getting_started/new_or_existing_website.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | +| [Create a `gitlab-ci.yml` file from scratch](getting_started_part_four.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +| [Use a new project template](getting_started/pages_bundled_template.md) | Create a new project with Pages already configured by using a new project template. | +| [Fork a sample project](getting_started/fork_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | + +To update a GitLab Pages website: + +| Document | Description | +| -------- | ----------- | +| [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md) | Learn about GitLab Pages default domains. | +| [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. | +| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. | +| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | +| [CloudFlare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. | + +Learn more and see examples: + +| Document | Description | +| -------- | ----------- | +| [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | Static versus dynamic site overview. | +| [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | SSG overview. | +| [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | Use SSGs for GitLab Pages. | -GitLab will always deploy your website from a very specific folder called `public` in your -repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md) +## How it works + +To use GitLab Pages, you must create a project in GitLab to upload your website's +files to. These projects can be either public, internal, or private. + +GitLab always deploys your website from a very specific folder called `public` in your +repository. When you create a new project in GitLab, a [repository](../repository/index.md) becomes available automatically. -To deploy your site, GitLab will use 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/README.md) to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. @@ -59,59 +87,29 @@ You can either use GitLab's [default domain for GitLab Pages websites](getting_s `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll need admin access to your domain's registrar (or control panel) to set it up with Pages. -### Getting started - -To get started with GitLab Pages, you can either: - -- [Use a bundled website template ready to go](getting_started/pages_bundled_template.md). -- [Copy an existing sample](getting_started/fork_sample_project.md). -- [Create a website from scratch or deploy an existing one](getting_started/new_or_existing_website.md). +The following diagrams show the workflows you might follow to get started with Pages. <img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> -Optional features: +## Access to your Pages site -- Use a [custom domain or subdomain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain). -- Add an [SSL/TLS certificate to secure your site under the HTTPS protocol](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages). - -Note that, if you're using GitLab Pages default domain (`.gitlab.io`), +If you're using GitLab Pages default domain (`.gitlab.io`), your website will be automatically secure and available under HTTPS. If you're using your own custom domain, you can optionally secure it with SSL/TLS certificates. -## Availability - If you're using GitLab.com, your website will be publicly available to the internet. - To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). -If you're using self-managed instances (Core, Starter, Premium, or Ultimate), +If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the [Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, -who can opt for making them public or internal to your server. +who can make them public or internal. -## Explore GitLab Pages +## Pages examples -To learn more about configuration options for GitLab Pages, read the following: - -| Document | Description | -| --- | --- | -| [GitLab Pages domain names, URLs, and baseurls](getting_started_part_one.md) | Understand how GitLab Pages default domains work. | -| [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | -| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD's configuration options, Access Control, custom 404 pages, limitations, FAQ. | -|---+---| -| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | -| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates automatically obtained and renewed by GitLab. | -| [CloudFlare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. | -|---+---| -| [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. | -| [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. | -| [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | An overview on using SSGs for GitLab Pages. | - -## Advanced use - -There are quite some great examples of GitLab Pages websites built for some -specific reasons. These examples can teach you some advanced techniques +There are some great examples of GitLab Pages websites built for +specific reasons. These examples can teach you advanced techniques to use and adapt to your own needs: - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/blog/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/). @@ -120,14 +118,9 @@ to use and adapt to your own needs: - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/). - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). -## Admin GitLab Pages for self-managed instances - -Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with -the [admin guide](../../../administration/pages/index.md). - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) for getting started with GitLab Pages admin!** +## Administer GitLab Pages for self-managed instances -## More information about GitLab Pages +If you are running a self-managed instance of GitLab (GitLab Community Edition and Enterprise Editions), +[follow the administration steps](../../../administration/pages/index.md) to configure Pages. -- Announcement (2016-12-24): ["We're bringing GitLab Pages to CE"](https://about.gitlab.com/releases/2016/12/24/were-bringing-gitlab-pages-to-community-edition/) -- Announcement (2017-03-06): ["We are changing the IP of GitLab Pages on GitLab.com"](https://about.gitlab.com/releases/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) about how to get started with GitLab Pages administration. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index e36dfd89ab3..614a0d0dd19 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -25,7 +25,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. A directory called `public` in your site's repo containing the content +1. A directory called `public` in your site's repository containing the content to be published. 1. GitLab Runner enabled for the project. @@ -87,7 +87,7 @@ will be deleted. When using Pages under the general domain of a GitLab instance (`*.example.io`), you _cannot_ use HTTPS with sub-subdomains. That means that if your -username/groupname contains a dot, for example `foo.bar`, the domain +username or group name contains a dot, for example `foo.bar`, the domain `https://foo.bar.example.io` will _not_ work. This is a limitation of the [HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages will continue to work provided you don't redirect HTTP to HTTPS. @@ -217,7 +217,7 @@ needing to compress files on-demand. ### Resolving ambiguous URLs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/95) in GitLab 11.8 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/95) in GitLab 11.8 GitLab Pages makes assumptions about which files to serve when receiving a request for a URL that does not include an extension. 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 33181828fb2..d86704eb703 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -105,7 +105,7 @@ operating systems the steps might be slightly different. Follow the therefore, it needs to be part of the website content under the repo's [`public`](index.md#how-it-works) folder. -1. Add, commit, and push the file into your repo in GitLab. Once the pipeline +1. Add, commit, and push the file into your repository in GitLab. Once the pipeline passes, press **Enter** on your terminal to continue issuing your certificate. CertBot will then prompt you with the following message: diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 7fe4c4c051d..6fcad0a5357 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages Access Control -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. > - Available on GitLab.com in GitLab 12.4. You can enable Pages access control on your project, so that only diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index e2ee0dd47fe..d0baf57f169 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -2,7 +2,7 @@ type: reference, howto --- -# Protected Branches +# Protected branches [Permissions](../permissions.md) in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -114,7 +114,7 @@ all matching branches: ## Creating a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53361) in GitLab 11.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. 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), @@ -134,7 +134,7 @@ To create a new branch through the user interface: ## Deleting a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/21393) in GitLab 9.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3. From time to time, it may be required to delete or clean up branches that are protected. @@ -155,7 +155,7 @@ command line or a Git client application. ## Protected Branches approval by Code Owners **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. It is possible to require at least one approval by a [Code Owner](code_owners.md) to a file changed by the @@ -194,11 +194,11 @@ for details about the pipelines security model. **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. +- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. **9.2** -- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/issues/21393)). +- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)). **8.11** diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index b134d283ba9..e80b8098bec 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -2,13 +2,13 @@ type: reference, howto --- -# Protected Tags +# Protected tags > [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 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. -This feature evolved out of [Protected Branches](protected_branches.md) +This feature evolved out of [protected branches](protected_branches.md) ## Overview diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index eab88d59867..ca658c06647 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -36,7 +36,7 @@ You can use push options to skip a CI/CD pipeline, or pass environment 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 [environment 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 [environment 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) | An example of using `ci.skip`: @@ -60,9 +60,9 @@ time as pushing changes: | `merge_request.create` | Create a new merge request for the pushed branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `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.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.label="<label>"` | Add labels to the merge request. If the label does not exist, it will be 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) | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index e2d0b616e4b..a3df173bd9d 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,5 +1,8 @@ --- type: reference +stage: Plan +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/#designated-technical-writers --- # GitLab Quick Actions @@ -10,7 +13,8 @@ You can enter these commands while creating a new issue or merge request, or in comments of issues, epics, merge requests, and commits. Each command should be on a separate line in order to be properly detected and executed. -> From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672), once an action is executed, an alert is displayed when a quick action is successfully applied. +> From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672), once an +> action is executed, an alert appears when a quick action is successfully applied. ## Quick Actions for issues, merge requests and epics @@ -18,63 +22,66 @@ The following quick actions are applicable to descriptions, discussions and thre - Issues - Merge requests -- Epics **(ULTIMATE)** - -| Command | Issue | Merge request | Epic | Action | -|:--------------------------------------|:------|:--------------|:-----|:------ | -| `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻` | -| `/shrug <comment>` | ✓ | ✓ | ✓ | Append the comment with `¯\＿(ツ)＿/¯` | -| `/todo` | ✓ | ✓ | ✓ | Add a To Do | -| `/done` | ✓ | ✓ | ✓ | Mark To Do as done | -| `/subscribe` | ✓ | ✓ | ✓ | Subscribe | -| `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe | -| `/close` | ✓ | ✓ | ✓ | Close | -| `/reopen` | ✓ | ✓ | ✓ | Reopen | -| `/title <new title>` | ✓ | ✓ | ✓ | Change title | -| `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award | -| `/assign me` | ✓ | ✓ | | Assign yourself | -| `/assign @user` | ✓ | ✓ | | Assign one user | -| `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users **(STARTER)** | -| `/reassign @user1 @user2` | ✓ | ✓ | | Change assignee **(STARTER)** | -| `/unassign` | ✓ | ✓ | | Remove current assignee | -| `/unassign @user1 @user2` | ✓ | ✓ | | Remove assignee(s) **(STARTER)** | -| `/milestone %milestone` | ✓ | ✓ | | Set milestone | -| `/remove_milestone` | ✓ | ✓ | | Remove milestone | -| `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add label(s). Label names can also start without `~` but mixed syntax is not supported | -| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace existing label(s) with those specified | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove all or specific label(s) | -| `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project | -| `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project | -| `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m` | -| `/remove_estimate` | ✓ | ✓ | | Remove time estimate | -| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Add spent time; optionally specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)` | -| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Subtract spent time; optionally specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)` | -| `/remove_time_spent` | ✓ | ✓ | | Remove time spent | -| `/lock` | ✓ | ✓ | | Lock the thread | -| `/unlock` | ✓ | ✓ | | Unlock the thread | -| `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st` | -| `/remove_due_date` | ✓ | | | Remove due date | -| `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, etc **(STARTER)** | -| `/clear_weight` | ✓ | | | Clear weight **(STARTER)** | -| `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(ULTIMATE)** | -| `/remove_epic` | ✓ | | | Remove from epic **(ULTIMATE)** | -| `/promote` | ✓ | | | Promote issue to epic **(ULTIMATE)** | -| `/confidential` | ✓ | | | Make confidential | -| `/duplicate <#issue>` | ✓ | | | Mark this issue as a duplicate of another issue and relate them for **(STARTER)** | -| `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue | -| `/relate #issue1 #issue2` | ✓ | | | Mark issues as related **(STARTER)** | -| `/move <path/to/project>` | ✓ | | | Move this issue to another project | -| `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue. ([Introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)) | -| `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue. ([Introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)) | -| `/target_branch <local branch name>` | | ✓ | | Set target branch | -| `/wip` | | ✓ | | Toggle the Work In Progress status | -| `/approve` | | ✓ | | Approve the merge request **(STARTER)** | -| `/submit_review` | | ✓ | | Submit a pending review. ([Introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/issues/8041)) **(PREMIUM)** | -| `/merge` | | ✓ | | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), etc). | -| `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/issues/7330)) **(ULTIMATE)** | -| `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/issues/7330)) **(ULTIMATE)** | -| `/parent_epic <epic>` | | | ✓ | 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)) **(ULTIMATE)** | -| `/remove_parent_epic` | | | ✓ | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/issues/10556)) **(ULTIMATE)** | +- Epics **(PREMIUM)** + +| Command | Issue | Merge request | Epic | Action | +| :------------------------------------ | :---- | :------------ | :--- | :------------------------------------------------------------------------------------------------------------------------------ | +| `/approve` | | ✓ | | Approve the merge request. **(STARTER)** | +| `/assign @user` | ✓ | ✓ | | Assign one user. | +| `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | +| `/assign me` | ✓ | ✓ | | Assign yourself. | +| `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | +| `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | +| `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | +| `/close` | ✓ | ✓ | ✓ | Close. | +| `/confidential` | ✓ | | | Make confidential. | +| `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue. | +| `/done` | ✓ | ✓ | ✓ | Mark To-Do as done. | +| `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/duplicate <#issue>` | ✓ | | | Mark this issue as a duplicate of another issue and mark them as related. **(STARTER)** | +| `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | +| `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | +| `/iteration *iteration:iteration` | ✓ | | | Set iteration ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | +| `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/lock` | ✓ | ✓ | | Lock the thread. | +| `/merge` | | ✓ | | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), adding to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), etc. | +| `/milestone %milestone` | ✓ | ✓ | | Set milestone. | +| `/move <path/to/project>` | ✓ | | | Move this issue to another project. | +| `/parent_epic <epic>` | | | ✓ | 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)). **(ULTIMATE)** | +| `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | +| `/publish` | ✓ | | | Publish issue to an associated [Status Page](status_page/index.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | +| `/reassign @user1 @user2` | ✓ | ✓ | | Change assignee. **(STARTER)** | +| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace existing labels with those specified. | +| `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | +| `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | +| `/remove_due_date` | ✓ | | | Remove due date. | +| `/remove_epic` | ✓ | | | Remove from epic. **(PREMIUM)** | +| `/remove_estimate` | ✓ | ✓ | | Remove time estimate. | +| `/remove_iteration` | ✓ | | | Remove iteration ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)) **(STARTER)** | +| `/remove_milestone` | ✓ | ✓ | | Remove milestone. | +| `/remove_parent_epic` | | | ✓ | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). **(ULTIMATE)** | +| `/remove_time_spent` | ✓ | ✓ | | Remove time spent. | +| `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/reopen` | ✓ | ✓ | ✓ | Reopen. | +| `/shrug <comment>` | ✓ | ✓ | ✓ | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time(-<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend time(-1h 30m)` or `/spend time(-1h 30m) date(2018-08-26)`. | +| `/spend <time(<h>h <mm>m)> <date(<YYYY-MM-DD>)>` | ✓ | ✓ | | Add spent time. Optionally, specify the date that time was spent on. For example, `/spend time(1h 30m)` or `/spend time(1h 30m) date(2018-08-26)`. | +| `/submit_review` | | ✓ | | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). **(PREMIUM)** | +| `/subscribe` | ✓ | ✓ | ✓ | Subscribe to notifications. | +| `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | | ✓ | | Set target branch. | +| `/title <new title>` | ✓ | ✓ | ✓ | Change title. | +| `/todo` | ✓ | ✓ | ✓ | Add a To-Do. | +| `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | +| `/unassign` | ✓ | ✓ | | Remove all assignees. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove all or specific labels. | +| `/unlock` | ✓ | ✓ | | Unlock the thread. | +| `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe from notifications. | +| `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. **(STARTER)** | +| `/wip` | | ✓ | | Toggle the Work In Progress status. | +| `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Autocomplete characters @@ -86,11 +93,11 @@ to enter a parameter, compared to selecting items from a list. The easiest way to set parameters for quick actions is to use autocomplete. If you manually enter a parameter, it must be enclosed in double quotation marks -(`"`), unless it contains only: +(`"`), unless it contains only these characters: 1. ASCII letters. -1. Numerals. -1. Underscore, hyphen, question mark, dot, and ampersand. +1. Numerals (0-9). +1. Underscore (`_`), hyphen (`-`), question mark (`?`), dot (`.`), or ampersand (`&`). Parameters are also case-sensitive. Autocomplete handles this, and the insertion of quotation marks, automatically. @@ -100,7 +107,7 @@ of quotation marks, automatically. The following quick actions are applicable for commit messages: | Command | Action | -|:------------------------|:------------------------------------------| +| :---------------------- | :---------------------------------------- | | `/tag v1.2.3 <message>` | Tags this commit with an optional message | <!-- ## Troubleshooting diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index bdb99d16625..58d143fb32b 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41766) in GitLab 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. It is typical to create a [Git tag](../../../university/training/topics/tags.md) at the moment of release to introduce a checkpoint in your source code @@ -67,9 +67,11 @@ 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. +The four types of links are "Runbook," "Package," "Image," and "Other." + #### Permanent links to Release assets -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27300) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. The assets associated with a Release are accessible through a permanent URL. GitLab will always redirect this URL to the actual asset @@ -105,7 +107,7 @@ The physical location of the asset can change at any time and the direct link wi ### Releases associated with milestones -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29020) in GitLab 12.5. > - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/39467) to edit milestones in the UI in GitLab 13.0. Releases can optionally be associated with one or more @@ -141,7 +143,7 @@ project. ### Number of Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36667) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36667) in GitLab 12.8. The incremental number of Releases is displayed on the project's details page. When clicked, it takes you to the list of Releases. @@ -154,7 +156,7 @@ it is displayed to every user regardless of their permission level. ### Upcoming Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/38105) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. A Release may be created ahead of time by specifying a future `released_at` date. Until the `released_at` date and time is reached, an **Upcoming Release** badge will appear next to the @@ -186,7 +188,7 @@ we recommend doing this as one of the last steps in your CI/CD release pipeline. ## Editing a release -> [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. +> [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. To edit the details of a release, navigate to **Project overview > Releases** and click the edit button (pencil icon) in the top-right corner of the release you want to modify. @@ -205,7 +207,7 @@ through the **Edit Release** page is planned for a future version of GitLab. ## Notification for Releases -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26001) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26001) in GitLab 12.4. You can be notified by email when a new Release is created for your project. @@ -243,7 +245,7 @@ You can also edit an existing tag to add release notes: ## Release Evidence -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26019) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. This data is called Release Evidence. It includes linked milestones and issues, and @@ -256,7 +258,7 @@ can have multiple Release Evidence snapshots. You can view the Release Evidence its details on the Release page. NOTE: **Note:** -When the issue tracker is disabled, release evidence [is not collected](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). +When the issue tracker is disabled, release evidence [cannot be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). Release Evidence is stored as a JSON object, so you can compare evidence by using commonly-available tools. @@ -267,11 +269,16 @@ Here is an example of a Release Evidence object: { "release": { "id": 5, - "tag": "v4.0", + "tag_name": "v4.0", "name": "New release", - "project_id": 45, - "project_name": "Project name", - "released_at": "2019-06-28 13:23:40 UTC", + "project": { + "id": 20, + "name": "Project name", + "created_at": "2019-04-14T11:12:13.940Z", + "description": "Project description" + }, + "created_at": "2019-06-28 13:23:40 UTC", + "description": "Release description", "milestones": [ { "id": 11, @@ -311,7 +318,7 @@ Here is an example of a Release Evidence object: } ``` -### Enabling Release Evidence display **(CORE ONLY)** +### Diabling Release Evidence display **(CORE ONLY)** This feature comes with the `:release_evidence_collection` feature flag enabled by default in GitLab self-managed instances. To turn it off, @@ -393,6 +400,8 @@ deploy_to_production: - if: $CI_DEPLOY_FREEZE == null ``` +For more information, see [Deployment safety](../../../ci/environments/deployment_safety.md). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index a49701017f3..75a84e36169 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -46,7 +46,7 @@ You can use [repository mirroring](repository_mirroring.md) to keep your fork sy The main difference is that with repository mirroring your remote fork will be automatically kept up-to-date. -Without mirroring, to work locally you'll have to use `git pull` to update your local repo +Without mirroring, to work locally you'll have to use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. CAUTION: **Caution:** diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 2deb53b313c..e63b57747ef 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -25,7 +25,7 @@ for that commit. ## Blame previous commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/19299) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19299) in GitLab 12.7. To see earlier revisions of a specific line, click **View blame prior to this change** until you've found the changes you're interested in viewing: diff --git a/doc/user/project/repository/img/repository_cleanup.png b/doc/user/project/repository/img/repository_cleanup.png Binary files differdeleted file mode 100644 index e343f23ac27..00000000000 --- a/doc/user/project/repository/img/repository_cleanup.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 055443daa1f..48975b7864e 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -27,7 +27,7 @@ that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files -Use a repository to store your files in GitLab. From [GitLab 12.10 onwards](https://gitlab.com/gitlab-org/gitlab/issues/33806), +Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), you'll see on the repository's file tree an icon next to the file name according to its extension: @@ -84,9 +84,9 @@ according to the markup language. | [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` | | [Textile](https://textile-lang.com/) | `textile` | | [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | -| [Orgmode](https://orgmode.org/) | `org` | +| [Org mode](https://orgmode.org/) | `org` | | [creole](http://www.wikicreole.org/) | `creole` | -| [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | +| [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | ### Repository README and index files @@ -116,7 +116,7 @@ user's sessions and include code, narrative text, equations, and rich output. ### OpenAPI viewer -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/19515) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6. GitLab can render OpenAPI specification files with its file viewer, provided their filenames include `openapi` or `swagger` and their extension is `yaml`, @@ -219,7 +219,9 @@ vendored code, and most markup languages are excluded. This behavior can be adjusted by overriding the default. For example, to enable `.proto` files to be detected, add the following to `.gitattributes` in the root of your repository. -> *.proto linguist-detectable=true +```plaintext +*.proto linguist-detectable=true +``` ## Locked files **(PREMIUM)** @@ -232,7 +234,7 @@ You can access your repos via [repository API](../../../api/repositories.md). ## Clone in Apple Xcode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/45820) in GitLab 11.0 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0 Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned in Xcode using the new **Open in Xcode** button, located next to the Git URL @@ -240,7 +242,7 @@ used for cloning your project. The button is only shown on macOS. ## Download Source Code -> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/24704) in GitLab 11.11. +> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. The source code stored in a repository can be downloaded from the UI. By clicking the download icon, a dropdown will open with links to download the following: diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index ca82be280d9..1948b12aacd 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,6 +1,6 @@ # Jupyter Notebook Files -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2508/) in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. [Jupyter](https://jupyter.org/) Notebook (previously IPython Notebook) files are used for interactive computing in many fields and contain a complete record of the diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 16bffe5417d..124150c441a 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,150 +1,244 @@ --- +stage: Create +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- -# Reducing the repository size using Git - -A GitLab Enterprise Edition administrator can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md) -which will prevent you from exceeding it. - -When a project has reached its size limit, you will not be able to push to it, -create a new merge request, or merge existing ones. You will still be able to -create new issues, and clone the project though. Uploading LFS objects will -also be denied. - -If you exceed the repository size limit, your first thought might be to remove -some data, make a new commit and push back to the repository. Perhaps you can -move some blobs to LFS, or remove some old dependency updates from history. -Unfortunately, it's not so easy and that workflow won't work. Deleting files in -a commit doesn't actually reduce the size of the repo since the earlier commits -and blobs are still around. What you need to do is rewrite history with Git's -[`filter-branch` option](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#The-Nuclear-Option:-filter-branch), -or an open source community-maintained tool like the -[BFG](https://rtyley.github.io/bfg-repo-cleaner/). - -Note that even with that method, until `git gc` runs on the GitLab side, the -"removed" commits and blobs will still be around. You also need to be able to -push the rewritten history to GitLab, which may be impossible if you've already -exceeded the maximum size limit. +# Reduce repository size -In order to lift these restrictions, the administrator of the GitLab instance -needs to increase the limit on the particular project that exceeded it, so it's -always better to spot that you're approaching the limit and act proactively to -stay underneath it. If you hit the limit, and your admin can't - or won't - -temporarily increase it for you, your only option is to prune all the unneeded -stuff locally, and then create a new project on GitLab and start using that -instead. +Git repositories become larger over time. When large files are added to a Git repository: -If you can continue to use the original project, we recommend [using -BFG](#using-the-bfg-repo-cleaner), a tool that's built and -maintained by the open source community. It's faster and simpler than -`git filter-branch`, and GitLab can use its account of what has changed to clean -up its own internal state, maximizing the space saved. +- Fetching the repository becomes slower because everyone must download the files. +- They take up a large amount of storage space on the server. +- Git repository storage limits [can be reached](#storage-limits). -CAUTION: **Caution:** -Make sure to first make a copy of your repository since rewriting history will -purge the files and information you are about to delete. Also make sure to -inform any collaborators to not use `pull` after your changes, but use `rebase`. +Rewriting a repository can remove unwanted history to make the repository smaller. +[`git filter-repo`](https://github.com/newren/git-filter-repo) is a tool for quickly rewriting Git +repository history, and is recommended over both: -CAUTION: **Caution:** -This process is not suitable for removing sensitive data like password or keys -from your repository. Information about commits, including file content, is -cached in the database, and will remain visible even after they have been -removed from the repository. +- [`git filter-branch`](https://git-scm.com/docs/git-filter-branch). +- [BFG](https://rtyley.github.io/bfg-repo-cleaner/). + +DANGER: **Danger:** +Rewriting repository history is a destructive operation. Make sure to backup your repository before +you begin. The best way back up a repository is to +[export the project](../settings/import_export.md#exporting-a-project-and-its-data). -## Using the BFG Repo-Cleaner +## Purge files from repository history -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/19376) in GitLab 11.6. +To make cloning your project faster, rewrite branches and tags to remove unwanted files. -1. [Install BFG](https://rtyley.github.io/bfg-repo-cleaner/) from its open source community repository. +1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/master/INSTALL.md) + using a supported package manager or from source. -1. Navigate to your repository: +1. Clone a fresh copy of the repository using `--bare`: ```shell - cd my_repository/ + git clone --bare https://example.gitlab.com/my/project.git ``` -1. Change to the branch you want to remove the big file from: +1. Using `git filter-repo`, purge any files from the history of your repository. + + To purge all large files, the `--strip-blobs-bigger-than` option can be used: ```shell - git checkout master + git filter-repo --strip-blobs-bigger-than 10M ``` -1. Create a commit removing the large file from the branch, if it still exists: + To purge specific large files by path, the `--path` and `--invert-paths` options can be combined: ```shell - git rm path/to/big_file.mpg - git commit -m 'Remove unneeded large file' + git filter-repo --path path/to/big/file.m4v --invert-paths ``` -1. Rewrite history: + See the + [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) + for more examples and the complete documentation. + +1. Running `git filter-repo` removes all remotes. To restore the remote for your project, run: ```shell - bfg --delete-files path/to/big_file.mpg + git remote add origin https://example.gitlab.com/<namespace>/<project_name>.git ``` - An object map file will be written to `object-id-map.old-new.txt`. Keep it - around - you'll need it for the final step! +1. Force push your changes to overwrite all branches on GitLab: -1. Force-push the changes to GitLab: + ```shell + git push origin --force --all + ``` + + [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + remove branch protection, push, and then re-enable protected branches. + +1. To remove large files from tagged releases, force push your changes to all tags on GitLab: ```shell - git push --force-with-lease origin master + git push origin --force --tags ``` - If this step fails, someone has changed the `master` branch while you were - rewriting history. You could restore the branch and re-run BFG to preserve - their changes, or use `git push --force` to overwrite their changes. + [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + protection, push, and then re-enable protected tags. -1. Navigate to **Project > Settings > Repository > Repository Cleanup**: +## Purge files from GitLab storage -  +To reduce the size of your repository in GitLab, you must remove GitLab internal references to +commits that contain large files. Before completing these steps, +[purge files from your repository history](#purge-files-from-repository-history). - Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. - This will remove any internal Git references to the old commits, and run - `git gc` against the repository. You will receive an email once it has - completed. +As well as [branches](branches/index.md) and tags, which are a type of Git ref, GitLab automatically +creates other refs. These refs prevent dead links to commits, or missing diffs when viewing merge +requests. [Repository cleanup](#repository-cleanup) can be used to remove these from GitLab. -NOTE: **Note:** -This process will remove some copies of the rewritten commits from GitLab's -cache and database, but there are still numerous gaps in coverage - at present, -some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) -may help to remove some of them, but it should not be depended on for security -purposes! +The following internal refs are not advertised: -## Using `git filter-branch` +- `refs/merge-requests/*` for merge requests. +- `refs/pipelines/*` for + [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). +- `refs/environments/*` for environments. -1. Navigate to your repository: +This means they are not usually included when fetching, which makes fetching faster. In addition, +`refs/keep-around/*` are hidden refs to prevent commits with discussion from being deleted and +cannot be fetched at all. - ```shell - cd my_repository/ - ``` +However, these refs can be accessed from the Git bundle inside a project export. -1. Change to the branch you want to remove the big file from: +1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/master/INSTALL.md) + using a supported package manager or from source. + +1. Generate a fresh [export from the + project](../settings/import_export.html#exporting-a-project-and-its-data) and download it. + +1. Decompress the backup using `tar`: ```shell - git checkout master + tar xzf project-backup.tar.gz ``` -1. Use `filter-branch` to remove the big file: + This will contain a `project.bundle` file, which was created by + [`git bundle`](https://git-scm.com/docs/git-bundle). + +1. Clone a fresh copy of the repository from the bundle: ```shell - git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD + git clone --bare --mirror /path/to/project.bundle ``` -1. Instruct Git to purge the unwanted data: +1. Using `git filter-repo`, purge any files from the history of your repository. Because we are + trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + which internal refs to remove. + + NOTE:**Note:** + `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from + the previous run. You will need this file from **every** run. Do the next step every time you run + `git filter-repo`. + + To purge all large files, the `--strip-blobs-bigger-than` option can be used: ```shell - git reflog expire --expire=now --all && git gc --prune=now --aggressive + git filter-repo --strip-blobs-bigger-than 10M ``` -1. Lastly, force push to the repository: + To purge specific large files by path, the `--path` and `--invert-paths` options can be combined. ```shell - git push --force origin master + git filter-repo --path path/to/big/file.m4v --invert-paths ``` -Your repository should now be below the size limit. + See the + [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) + for more examples and the complete documentation. + +1. Run a [repository cleanup](#repository-cleanup). + +## Repository cleanup + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. + +Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git +references to these objects. You can use +[`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a +`commit-map` file) that can be used with repository cleanup. + +To clean up a repository: + +1. Go to the project for the repository. +1. Navigate to **{settings}** **Settings > Repository**. +1. Upload a list of objects. For example, a `commit-map` file. +1. Click **Start cleanup**. + +This will: + +- Remove any internal Git references to old commits. +- Run `git gc` against the repository. + +You will receive an email once it has completed. + +When using repository cleanup, note: + +- Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks + will not be removed immediately. If you have access to the + [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to + prune all loose objects immediately. +- This process will remove some copies of the rewritten commits from GitLab's cache and database, + but there are still numerous gaps in coverage and some of the copies may persist indefinitely. + [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) + may help to remove some of them, but it should not be depended on for security purposes! + +## Storage limits + +Repository size limits: + +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#repository-size-limit-starter-only) + on self-managed instances. **(STARTER ONLY)** +- Are [set for GitLab.com](../../gitlab_com/index.md#repository-size-limit). + +When a project has reached its size limit, you cannot: + +- Push to the project. +- Create a new merge request. +- Merge existing merge requests. +- Upload LFS objects. + +You can still: + +- Create new issues. +- Clone the project. + +If you exceed the repository size limit, you might try to: + +1. Remove some data. +1. Make a new commit. +1. Push back to the repository. + +Perhaps you might also: + +- Move some blobs to LFS. +- Remove some old dependency updates from history. + +Unfortunately, this workflow won't work. Deleting files in a commit doesn't actually reduce the size +of the repository because the earlier commits and blobs still exist. + +What you need to do is rewrite history. We recommend the open-source community-maintained tool +[`git filter-repo`](https://github.com/newren/git-filter-repo). + +NOTE: **Note:** +Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +must be able to push the rewritten history to GitLab, which may be impossible if you've already +exceeded the maximum size limit. + +In order to lift these restrictions, the administrator of the self-managed GitLab instance must +increase the limit on the particular project that exceeded it. Therefore, it's always better to +proactively stay underneath the limit. If you hit the limit, and can't have it temporarily +increased, your only option is to: + +1. Prune all the unneeded stuff locally. +1. Create a new project on GitLab and start using that instead. + +CAUTION: **Caution:** +This process is not suitable for removing sensitive data like password or keys from your repository. +Information about commits, including file content, is cached in the database, and will remain +visible even after they have been removed from the repository. <!-- ## Troubleshooting diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index fdbea385998..f75b083e6dc 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -28,7 +28,7 @@ immediate update, unless: - The mirror is already being updated. - 5 minutes haven't elapsed since its last update. -For security reasons, from [GitLab 12.10 onwards](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), +For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), the URL to the original repository is only displayed to users with Maintainer or Owner permissions to the mirrored project. @@ -134,7 +134,7 @@ The repository will push soon. To force a push, click the appropriate button. ## Pulling from a remote repository **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. -> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. @@ -356,6 +356,24 @@ a [Push event webhook](../integrations/webhooks.md#push-events) to trigger an im pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring 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-starter) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. + +To do this: + +- Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. +- Navigate to **Settings > Webhooks** +- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter) 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> + ``` + +- Ensure that the **Push Events** checkbox is selected. +- Click on **Add Webhook** button to save the webhook. +- To test the integration click on the **Test** button and confirm GitLab does not return any error. + ### Preventing conflicts using a `pre-receive` hook CAUTION: **Warning:** @@ -388,13 +406,13 @@ proxy_push() REFNAME="$3" # --- Pattern of branches to proxy pushes - whitelisted=$(expr "$branch" : "\(master\)") + allowlist=$(expr "$branch" : "\(master\)") case "$refname" in refs/heads/*) branch=$(expr "$refname" : "refs/heads/\(.*\)") - if [ "$whitelisted" = "$branch" ]; then + if [ "$allowlist" = "$branch" ]; then unset GIT_QUARANTINE_PATH # handle https://git-scm.com/docs/git-receive-pack#_quarantine_environment error="$(git push --quiet $TARGET_REPO $NEWREV:$REFNAME 2>&1)" fail=$? @@ -435,7 +453,7 @@ Note that this sample has a few limitations: - This example may not work verbatim for your use case and might need modification. - It does not regard different types of authentication mechanisms for the mirror. - It does not work with forced updates (rewriting history). - - Only branches that match the `whitelisted` patterns will be proxy pushed. + - Only branches that match the `allowlist` patterns will be proxy pushed. - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update and Git will complain about it. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 20143af0b33..d55d5c5c2d8 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -65,11 +65,11 @@ git config --global gpg.format x509 ### Windows and MacOS -Install [smimesign](https://github.com/github/smimesign) by downloading the +Install [S/MIME Sign](https://github.com/github/smimesign) by downloading the installer or via `brew install smimesign` on MacOS. Get the ID of your certificate with `smimesign --list-keys` and set your -signingkey `git config --global user.signingkey ID`, then configure X.509: +signing key `git config --global user.signingkey ID`, then configure X.509: ```shell git config --global gpg.x509.program smimesign diff --git a/doc/user/project/requirements/img/requirement_edit_save_v12_10.png b/doc/user/project/requirements/img/requirement_edit_save_v12_10.png Binary files differdeleted file mode 100644 index 6cf7db361b8..00000000000 --- a/doc/user/project/requirements/img/requirement_edit_save_v12_10.png +++ /dev/null diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 50343e52a68..d9bd02518a4 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,14 +1,23 @@ --- type: reference, howto +stage: Plan +group: Certify +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Requirements **(ULTIMATE)** +# Requirements Management **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -Requirements allow you to create criteria to check your products against. They -can be based on users, stakeholders, system, software, or anything else you -find important to capture. +With requirements, you can set criteria to check your products against. They can be based on users, +stakeholders, system, software, or anything else you find important to capture. + +A requirement is an artifact in GitLab which describes the specific behavior of your product. +Requirements are long-lived and don't disappear unless manually cleared. + +If an industry standard *requires* that your application has a certain feature or behavior, you can +[create a requirement](#create-a-requirement) to reflect this. +When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). @@ -38,22 +47,18 @@ list page. To edit a requirement: -1. From the requirements list, click the **Edit** (**{pencil}**) button. +1. From the requirements list, click **Edit** (**{pencil}**). 1. Update the title in text input field. 1. Click **Save changes**.  -The requirements list shows the new title immediately. - - - ## Archive a requirement You can archive an open requirement (if you have the necessary privileges) while you're in the **Open** tab. -From the requirements list page, click the **Archive** (**{archive}**) button. +From the requirements list page, click **Archive** (**{archive}**).  @@ -65,6 +70,84 @@ You can view the list of archived requirements in the **Archived** tab.  -To reopen an archived requirement, click the **Reopen** button. +To reopen an archived requirement, click **Reopen**. As soon as a requirement is reopened, it no longer appears in the **Archived** tab. + +## Search for a requirement from the requirements list page + +> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +You can search for a requirement from the list of requirements using filtered search bar (similar to +that of Issues and Merge Requests) based on following parameters: + +- Title +- Author username + +To search, go to the list of requirements and click the field **Search or filter results**. +It will display a dropdown menu, from which you can add an author. You can also enter plain +text to search by epic title or description. When done, press <kbd>Enter</kbd> on your +keyboard to filter the list. + +You can also sort requirements list by: + +- Created date +- Last updated + +## Allow requirements to be satisfied from a CI job + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +GitLab supports [requirements test +reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements-ultimate) now. +You can add a job to your CI pipeline that, when triggered, marks all existing +requirements as Satisfied. + +### Add the manual job to CI + +To configure your CI to mark requirements as Satisfied when the manual job is +triggered, add the code below to your `.gitlab-ci.yml` file. + +```yaml +requirements_confirmation: + when: manual + allow_failure: false + script: + - mkdir tmp + - echo "{\"*\":\"passed\"}" > tmp/requirements.json + artifacts: + reports: + requirements: tmp/requirements.json +``` + +This definition adds a manually-triggered (`when: manual`) job to the CI +pipeline. It's blocking (`allow_failure: false`), but it's up to you what +conditions you use for triggering the CI job. Also, you can use any existing CI job +to mark all requirements as satisfied, as long as the `requirements.json` +artifact is generated and uploaded by the CI job. + +When you manually trigger this job, the `requirements.json` file containing +`{"*":"passed"}` is uploaded as an artifact to the server. On the server side, +the requirement report is checked for the "all passed" record +(`{"*":"passed"}`), and on success, it marks all existing open requirements as +Satisfied. + +### Add the manual job to CI conditionally + +To configure your CI to include the manual job only when there are some open +requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI variable. + +```yaml +requirements_confirmation: + rules: + - if: "$CI_HAS_OPEN_REQUIREMENTS" == "true" + when: manual + - when: never + allow_failure: false + script: + - mkdir tmp + - echo "{\"*\":\"passed\"}" > tmp/requirements.json + artifacts: + reports: + requirements: tmp/requirements.json +``` diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index d021f259015..ffb1f6a1407 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,6 +1,13 @@ +--- +stage: Plan +group: Certify +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Service Desk **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/149) in [GitLab Premium 9.1](https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#service-desk-eep). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. ## Overview @@ -28,14 +35,19 @@ with GitLab CI/CD. Here's how Service Desk will work for you: -1. You'll provide a project-specific email address to your paying customers, who can email you directly from within the app -1. Each email they send creates an issue in the appropriate project -1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues -1. Your team communicates back and forth with the customer to understand the request -1. Your team starts working on implementing code to solve your customer's problem -1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically -1. The customer will have been attended successfully via email, without having real access to your GitLab instance -1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer +1. You provide a project-specific email address to your paying customers, who can email you directly + from within the app. +1. Each email they send creates an issue in the appropriate project. +1. Your team members navigate to the Service Desk issue tracker, where they can see new support + requests and respond inside associated issues. +1. Your team communicates back and forth with the customer to understand the request. +1. Your team starts working on implementing code to solve your customer's problem. +1. When your team finishes the implementation, whereupon the merge request is merged and the issue + is closed automatically. +1. The customer will have been attended successfully via email, without having real access to your + GitLab instance. +1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with + your customer. ## How it works @@ -56,7 +68,8 @@ If you have the correct access and a Premium license, you have the option to set Follow these steps to do so: 1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - This must support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). + - We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). 1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues to the project. These issues will be [confidential](issues/confidential_issues.md), so they will @@ -83,7 +96,7 @@ navigation's **Issues** menu. ### Using customized email templates - > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. + > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. @@ -110,14 +123,14 @@ in the email, `%{ISSUE_PATH}` placeholder which will be replaced by ### Using custom email display name -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7529) in GitLab 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. You can customize the email display name. Emails sent from Service Desk will have this name in the `From` header. The default display name is `GitLab Support Bot`. ### Using custom email address -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. NOTE: **Note:** This feature is disabled by default. For steps to enable it, see [Enable custom email address](#enable-custom-email-address). @@ -160,12 +173,12 @@ As a result, a new Service Desk issue is created from this email in the `mygroup #### Enable custom email address -This feature comes with the `service_desk_email` feature flag disabled by default. +This feature comes with the `service_desk_custom_address` feature flag disabled by default. To turn on the feature, ask a GitLab administrator with Rails console access to run the following command: ```ruby -Feature.enable(service_desk_email) +Feature.enable(:service_desk_custom_address) ``` The configuration options are the same as for configuring diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index e9521a0567e..5a364eb89aa 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,6 +1,6 @@ # Project import/export -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/3050) in GitLab 8.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. > - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. Existing projects running on any GitLab instance or GitLab.com can be exported with all their related @@ -158,12 +158,16 @@ If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. +NOTE: **Note:** +The maximum import file size can be set by the Administrator, default is 50MB. +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). + ## Rate limits To help avoid abuse, users are rate limited to: -| Request Type | Limit | -| ---------------- | --------------------------- | -| Export | 1 project per 5 minutes | -| Download export | 10 projects per 10 minutes | -| Import | 30 projects per 5 minutes | +| Request Type | Limit | +| ---------------- | ----------------------------------------- | +| Export | 30 projects per 5 minutes | +| Download export | 10 downloads per project every 10 minutes | +| Import | 30 projects per 5 minutes | diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 0c98772237b..0798c39fff5 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -55,7 +55,7 @@ Use the switches to enable or disable the following features: | **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | | **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your docker images | +| **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-premium-only) functionality | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | @@ -192,11 +192,9 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -1. You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group. -1. The project is in a subgroup you own. -1. You're at least a **Maintainer** of the project under your personal namespace. - Similarly, if you're an owner of a group, you can transfer any of its projects - under your own user. +- You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group. +- You're at least an **Owner** of the project to be transferred. +- The group to which the project is being transferred to must allow creation of new projects. To transfer a project: @@ -228,14 +226,14 @@ To remove a project: This action either: - Removes a project including all associated resources (issues, merge requests etc). -- Since [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/32935), on +- Since [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/32935), on [GitLab Premium or GitLab.com Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a project for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only). #### Restore a project **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32935) in GitLab 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. To restore a project marked for deletion: @@ -272,3 +270,8 @@ Configure Error Tracking to discover and view [Sentry errors within GitLab](../o ### Jaeger tracing **(ULTIMATE)** Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md). + +### Status Page + +[Add Storage credentials](../status_page/#syncing-incidents-to-the-status-page) +to enable the syncing of public Issues to a [deployed status page](../status_page/#status-page-project). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 303a6f6d3be..42ba2654b42 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,6 +1,13 @@ -# Project access tokens **(CORE ONLY)** +# Project access tokens (Alpha) **(CORE ONLY)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. +CAUTION: **Warning:** +This is an [Alpha](https://about.gitlab.com/handbook/product/#alpha) feature, and it is subject to change at any time without +prior notice. + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. +> - It's deployed behind a feature flag, disabled by default. +> - It's disabled on GitLab.com. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-project-access-tokens). Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). @@ -27,7 +34,7 @@ For each project access token created, a bot user will also be created and added ["Maintainer" level permissions](../../permissions.md#project-members-permissions). API calls made with a project access token will be associated to the corresponding bot user. -These users will appear in **{settings}** **Settings > Members** but can not be modified. +These users will appear in **Members** but can not be modified. Furthermore, the bot user can not be added to any other project. When the project access token is [revoked](#revoking-a-project-access-token) the bot user will be deleted and all @@ -53,3 +60,22 @@ the following table. | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | + +### Enable or disable project access tokens + +Project access tokens is an [Alpha](https://about.gitlab.com/handbook/product/#alpha) feature and is not recommended 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 for your instance. + +To enable it: + +```ruby +Feature.enable(:resource_access_token) +``` + +To disable it: + +```ruby +Feature.disable(:resource_access_token) +``` diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 8ebfb638894..ec0a79583d5 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -55,7 +55,7 @@ To deploy the Status Page to AWS S3 you need to add the Status Page project & co Once the CI/CD variables are set, you'll need to set up the Project you want to use for Incident issues: -1. Navigate to **Settings > Operations > Status Page**. +1. To view the [Operations Settings](../settings/#operations-settings) page, navigate to **{settings}** **Settings > Operations > Status Page**. 1. Fill in your cloud provider's credentials and make sure the **Active** checkbox is checked. 1. Click **Save changes**. @@ -71,7 +71,8 @@ The incident detail page shows detailed information about a particular incident. - Status on the incident, including when the incident was last updated. - The incident title, including any emojis. -- The description of the incident, including emojis and static images. +- The description of the incident, including emojis. +- Any file attachments provided in the incident description or comments with a valid image extension. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205166) in GitLab 13.1. - A chronological ordered list of updates to the incident.  @@ -82,12 +83,21 @@ The incident detail page shows detailed information about a particular incident. To publish an Incident, you first need to create an issue in the Project you enabled the Status Page settings in. -Once this issue is created, a background worker will publish the issue onto the Status Page using the credentials you provided during setup. +Issues are not published to the Status Page by default. Use the `/publish` [quick action](../quick_actions.md) in an issue to publish the issue. Only [project or group owners](../../permissions.md) are permitted to publish issues. + +After the quick action is used, a background worker publishes the issue onto the Status Page using the credentials you provided during setup. + Since all incidents are published publicly, user and group mentions are anonymized with `Incident Responder`, and titles of non-public [GitLab references](../../markdown.md#special-gitlab-references) are removed. +When an Incident is published in the GitLab project, you can access the +details page of the Incident by clicking the **Published on status page** button +displayed under the Incident's title. + + + NOTE: **Note:** -Confidential issues are not published. If a published issue is made confidential it will be unpublished. +Confidential issues can't be published. If you make a published issue confidential, it will be unpublished. ### Publishing updates @@ -108,3 +118,15 @@ Anyone with access to view the Issue can add an Emoji Award to a comment, so you ### Changing the Incident status To change the incident status from `open` to `closed`, close the incident issue within GitLab. This will then be updated shortly on the Status Page website. + +## Attachment storage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205166) in GitLab 13.1. + +Beginning with GitLab 13.1, files attached to incident issue descriptions or +comments are published and unpublished to the status page storage as part of +the [publication flow](#how-it-works). + +### Limit + +Only 5000 attachments per issue will be transferred to the status page. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 57a26f4e928..b88e1ed2d37 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -1,6 +1,9 @@ --- type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' +stage: Plan +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/#designated-technical-writers --- # Time Tracking diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index d4daca0e1e4..0ddc9762bc5 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ # Web IDE -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/issues/44157) in 10.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. The Web IDE editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. @@ -57,10 +57,30 @@ which applies to the entire Web IDE screen. |---------------------------------------------------------------|-----------------------------------------| |  |  | +## Configure the Web IDE + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. + +The Web IDE supports configuration of certain editor settings by using +[`.editorconfig` files](https://editorconfig.org/). When opening a file, the +Web IDE looks for a file named `.editorconfig` in the current directory +and all parent directories. If a configuration file is found and has settings +that match the file's path, these settings will be enforced on the opened file. + +The Web IDE currently supports the following `.editorconfig` settings: + +- `indent_style` +- `indent_size` +- `end_of_line` +- `trim_trailing_whitespace` +- `tab_width` +- `insert_final_newline` + ## Commit changes -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4 and [brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/issues/44157) in 10.7. -> - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/issues/33441), files were automatically staged. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. > - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. After making your changes, click the **Commit** button on the bottom-left to @@ -116,6 +136,20 @@ in the top of the sidebar to open a list of branches. You will need to commit or discard all your changes before switching to a different branch. +## Markdown editing + +> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Core](https://about.gitlab.com/pricing/) 10.7. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. + +When you edit Markdown files in the Web IDE, you can preview your changes by +clicking the **Preview Markdown** tab above the file editor. The Markdown preview +supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +You can also upload any local images by pasting them directly in the Markdown file. +The image is uploaded to the same directory and is named `image.png` by default. +If another file already exists with the same name, a numeric suffix is automatically +added to the file name. + ## Live Preview > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. @@ -152,9 +186,10 @@ below. } ``` -## Interactive Web Terminals for the Web IDE **(ULTIMATE ONLY)** +## Interactive Web Terminals for the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. CAUTION: **Warning:** Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -252,7 +287,8 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Core in 13.1. File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal @@ -284,7 +320,7 @@ terminal: - The `webide-file-sync` executable must start **after** the project directory is available. This is why we need to add `sleep 5` to the `command`. - See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/issues/7) for + See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/-/issues/7) for more information. - `$CI_PROJECT_DIR` is a [predefined environment variable](../../../ci/variables/predefined_variables.md) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index fa3ad4536ef..82dbeb0ff7e 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -52,7 +52,7 @@ When you're ready, click the **Create page** and the new page will be created. ### Attachment storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33475) in GitLab 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. Starting with GitLab 11.3, any file that is uploaded to the wiki via GitLab's interface will be stored in the wiki Git repository, and it will be available @@ -185,6 +185,14 @@ them like you would do with every other Git repository. On the right sidebar, click on **Clone repository** and follow the on-screen instructions. +Files that you add to your wiki locally must have one of the following +supported extensions, depending on the markup language you wish to use, +otherwise they will not display when pushed to GitLab: + +- Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. +- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. +- Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`. + ## Customizing sidebar On the project's Wiki page, there is a right side navigation that renders the full Wiki pages list by default, with hierarchy. |
