diff options
Diffstat (limited to 'doc/user/project')
116 files changed, 1077 insertions, 819 deletions
diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 1acdc56de54..ff9cb1c712e 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -35,6 +35,8 @@ Autocomplete characters are useful when combined with [Quick Actions](quick_acti Assume your GitLab instance includes the following users: +<!-- vale gitlab.Spelling = NO --> + | Username | Name | | :-------------- | :--- | | alessandra | Rosy Grant | @@ -43,6 +45,8 @@ Assume your GitLab instance includes the following users: | logan_gutkowski | Lee Wuckert | | shelba | Josefine Haley | +<!-- vale gitlab.Spelling = YES --> + In an Issue comment, entering `@l` results in the following popup list appearing. Note that user `shelba` is not included, because the list includes only the 5 users most relevant to the Issue. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index ed6e2460554..fd0287fb5fb 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -10,7 +10,7 @@ type: reference, howto > [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 +projects. They consist of a small image and a URL that the image points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), [test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the project maintainers. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index b3b1b51a543..65416d73f06 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -43,7 +43,7 @@ For example, the following policy document allows assuming a role whose name sta Generate an access key for the IAM user, and configure GitLab with the credentials: -1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section. +1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. 1. Enter the account ID and access key credentials into the respective `Account ID`, `Access key ID` and `Secret access key` fields. @@ -61,22 +61,13 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an - `Account ID` and `External ID` to use in the next step. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. - To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions - to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. - In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` - policy for this role in order for GitLab to manage the EKS cluster correctly. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: - 1. From the left panel, select **Roles**. - 1. Click **Create role**. - 1. Under `Select type of trusted entity`, select **Another AWS account**. - 1. Enter the Account ID from GitLab into the `Account ID` field. - 1. Check **Require external ID**. - 1. Enter the External ID from GitLab into the `External ID` field. - 1. Click **Next: Permissions**. - 1. Click **Create Policy**, which will open a new window. - 1. Select the **JSON** tab, and paste in the following snippet in place of the existing content: + `Account ID` and `External ID` needed for later steps. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: + 1. From the left panel, select **Policies**. + 1. Click **Create Policy**, which opens a new window. + 1. Select the **JSON** tab, and paste the following snippet in place of the + existing content. These permissions give GitLab the ability to create + resources, but not delete them: ```json { @@ -123,15 +114,26 @@ To create and add a new Kubernetes cluster to your project, group, or instance: } ``` - NOTE: **Note:** - These permissions give GitLab the ability to create resources, but not delete them. - This means that if an error is encountered during the creation process, changes will + If an error is encountered during the creation process, changes will not be rolled back and you must remove resources manually. You can do this by deleting the relevant [CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html) 1. Click **Review policy**. 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. - 1. Switch back to the "Create role" window, and select the policy you just created. + +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. + To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions + to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. + In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` + policy for this role in order for GitLab to manage the EKS cluster correctly. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: + 1. From the left panel, select **Roles**. + 1. Click **Create role**. + 1. Under `Select type of trusted entity`, select **Another AWS account**. + 1. Enter the Account ID from GitLab into the `Account ID` field. + 1. Check **Require external ID**. + 1. Enter the External ID from GitLab into the `External ID` field. + 1. Click **Next: Permissions**, and select the policy you just created. 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. 1. Click **Next: Review**. 1. Enter a role name and optional description into the fields provided. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 18d9fa67ee1..094f4bcf6ba 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -19,9 +19,12 @@ and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform ( in a few clicks. TIP: **Tip:** -Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's -Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. +Every new Google Cloud Platform (GCP) account receives +[$300 in credit upon sign up](https://console.cloud.google.com/freetrial). +In partnership with Google, GitLab is able to offer an additional $200 for new GCP +accounts to get started with GitLab's Google Kubernetes Engine Integration. +[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) +to apply for credit. ## Before you begin @@ -30,7 +33,7 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - GitLab itself. Either: - A [GitLab.com account](https://about.gitlab.com/pricing/#gitlab-com). - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version - 12.5 or later. This will ensure the GitLab UI can be used for cluster creation. + 12.5 or later. This ensures the GitLab UI can be used for cluster creation. - The following GitLab access: - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a project-level cluster. @@ -41,28 +44,25 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need ## Access controls -When creating a cluster in GitLab, you will be asked if you would like to create either: +> - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. -- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster. -- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. +When creating a cluster in GitLab, you are asked if you would like to create either: -NOTE: **Note:** -[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. +- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) + cluster, which is the GitLab default and recommended option. +- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. GitLab creates the necessary service accounts and privileges to install and run [GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster, a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace to manage the newly created cluster. -NOTE: **Note:** -Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. - The first time you install an application into your cluster, the `tiller` service account is created with `cluster-admin` privileges in the -`gitlab-managed-apps` namespace. This service account will be used by Helm to +`gitlab-managed-apps` namespace. This service account is used by Helm to install and run [GitLab managed applications](index.md#installing-applications). -Helm will also create additional service accounts and other resources for each +Helm also creates additional service accounts and other resources for each installed application. Consult the documentation of the Helm charts for each application for details. @@ -77,7 +77,7 @@ Note the following about access controls: - Environment-specific resources are only created if your cluster is [managed by GitLab](index.md#gitlab-managed-clusters). -- If your cluster was created before GitLab 12.2, it will use a single namespace for all project +- If your cluster was created before GitLab 12.2, it uses a single namespace for all project environments. ### RBAC cluster resources @@ -151,11 +151,12 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level ## Add existing cluster -If you have an existing Kubernetes cluster, you can add it to a project, group, or instance. +If you have an existing Kubernetes cluster, you can add it to a project, group, +or instance. -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/-/issues/29838) for details. +Kubernetes integration isn't supported for arm64 clusters. See the issue +[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) +for details. ### Existing Kubernetes cluster @@ -181,7 +182,7 @@ To add a Kubernetes cluster to your project, group, or instance: 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. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default. 1. List the secrets with `kubectl get secrets`, and one should be named similar to `default-token-xxxxx`. Copy that token name for use below. 1. Get the certificate by running this command: @@ -190,9 +191,20 @@ To add a Kubernetes cluster to your project, group, or instance: 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. + If the command returns the entire certificate chain, you must copy the Root CA + certificate and any intermediate certificates at the bottom of the chain. + A chain file has following structure: + + ```plaintext + -----BEGIN MY CERTIFICATE----- + -----END MY CERTIFICATE----- + -----BEGIN INTERMEDIATE CERTIFICATE----- + -----END INTERMEDIATE CERTIFICATE----- + -----BEGIN INTERMEDIATE CERTIFICATE----- + -----END INTERMEDIATE CERTIFICATE----- + -----BEGIN ROOT CERTIFICATE----- + -----END ROOT CERTIFICATE----- + ``` 1. **Token** - GitLab authenticates against Kubernetes using service tokens, which are @@ -229,10 +241,10 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl apply -f gitlab-admin-service-account.yaml ``` - You will need the `container.clusterRoleBindings.create` permission + You need the `container.clusterRoleBindings.create` permission to create cluster-level roles. If you do not have this permission, you can alternatively enable Basic Authentication and then run the - `kubectl apply` command as an admin: + `kubectl apply` command as an administrator: ```shell kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> @@ -257,7 +269,7 @@ To add a Kubernetes cluster to your project, group, or instance: Copy the `<authentication_token>` value from the output: - ```yaml + ```plaintext Name: gitlab-token-b5zv4 Namespace: kube-system Labels: <none> @@ -274,7 +286,7 @@ To add a Kubernetes cluster to your project, group, or instance: ``` NOTE: **Note:** - For GKE clusters, you will need the + For GKE clusters, you need the `container.clusterRoleBindings.create` permission to create a cluster role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) @@ -283,7 +295,7 @@ To add a Kubernetes cluster to your project, group, or instance: 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: + it blank, GitLab creates one for you. Also: - Each project should have a unique namespace. - The project namespace is not necessarily the namespace of the secret, if you're using a secret with broader permissions, like the secret from `default`. @@ -294,21 +306,21 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster will be ready to go. You can now proceed +After a couple of minutes, your cluster is ready. You can now proceed to install some [pre-defined applications](index.md#installing-applications). #### Disable Role-Based Access Control (RBAC) (optional) When connecting a cluster via GitLab integration, you may specify whether the -cluster is RBAC-enabled or not. This will affect how GitLab interacts with the +cluster is RBAC-enabled or not. This affects how GitLab interacts with the cluster for certain operations. If you did *not* check the **RBAC-enabled cluster** -checkbox at creation time, GitLab will assume RBAC is disabled for your cluster +checkbox at creation time, GitLab assumes RBAC is disabled for your cluster when interacting with it. If so, you must disable RBAC on your cluster for the integration to work properly. - + -NOTE: **Note:** +CAUTION: **Caution:** Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](index.md#security-implications), and may not be desirable. @@ -356,3 +368,12 @@ When removing the cluster integration, note: To learn more on automatically deploying your applications, read about [Auto DevOps](../../../topics/autodevops/index.md). + +## Troubleshooting + +### There was a problem authenticating with your cluster. Please ensure your CA Certificate and Token are valid + +If you encounter this error while adding a Kubernetes cluster, ensure you're +properly pasting the service token. Some shells may add a line break to the +service token, making it invalid. Ensure that there are no line breaks by +pasting your token into an editor and removing any additional spaces. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 8d188f00ceb..459ba144186 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- @@ -12,8 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in > GitLab 11.11 for [instances](../../instance/clusters/index.md). -## Overview - Using the GitLab project Kubernetes integration, you can: - Use [Review Apps](../../../ci/review_apps/index.md). @@ -31,6 +29,11 @@ Besides integration at the project level, Kubernetes clusters can also be integrated at the [group level](../../group/clusters/index.md) or [GitLab instance level](../../instance/clusters/index.md). +To view your project level Kubernetes clusters, navigate to **Operations > Kubernetes** +from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters) +and view information about your existing clusters, such as nodes count and rough estimates +of memory and CPU usage. + ## Setting up ### Supported cluster versions @@ -49,10 +52,9 @@ Currently, GitLab supports the following Kubernetes versions: - 1.17 - 1.16 - 1.15 -- 1.14 +- 1.14 (deprecated, support ends on December 22, 2020) - 1.13 (deprecated, support ends on November 22, 2020) -NOTE: **Note:** Some GitLab features may support versions outside the range provided here. ### Adding and removing clusters @@ -192,7 +194,6 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. -NOTE: **Note:** You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). @@ -220,13 +221,11 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) you will need the Kubernetes project integration enabled. +Auto Monitoring) you will need the Kubernetes project integration enabled, but +Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) -NOTE: **Note:** -Kubernetes clusters can be used without Auto DevOps. - ## Deploying to a Kubernetes cluster A Kubernetes cluster can be the destination for a deployment job. If @@ -249,36 +248,51 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | -NOTE: **Note:** -Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main -service account of the cluster integration. - -NOTE: **Note:** -If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`. - ### Custom namespace -> [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 -variables](#deployment-variables)). - -For **non**-GitLab-managed clusters, the namespace can be customized using -[`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) -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). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. +> - An option to use project-wide namespaces [was added](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) in GitLab 13.5. + +The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace +to deployment jobs. It defaults to using project-environment specific namespaces +of the form `<prefix>-<environment>`, where `<prefix>` is of the form +`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables). + +You can customize the deployment namespace in a few ways: + +- You can choose between a **namespace per [environment](../../../ci/environments/index.md)** + or a **namespace per project**. A namespace per environment is the default and recommended + setting, as it prevents the mixing of resources between production and non-production environments. +- When using a project-level cluster, you can additionally customize the namespace prefix. + When using namespace-per-environment, the deployment namespace is `<prefix>-<environment>`, + but otherwise just `<prefix>`. +- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, + but the user is responsible for ensuring its existence. You can fully customize + this value using + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) + in `.gitlab-ci.yml`. + +When you customize the namespace, existing environments remain linked to their current +namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). + +CAUTION: **Warning:** +By default, anyone who can create a deployment job can access any CI variable within +an environment's deployment job. This includes `KUBECONFIG`, which gives access to +any secret available to the associated service account in your cluster. +To keep your production credentials safe, consider using +[Protected Environments](../../../ci/environments/protected_environments.md), +combined with either + +- a GitLab-managed cluster and namespace per environment, +- *or*, an environment-scoped cluster per protected environment. The same cluster + can be added multiple times with multiple restricted service accounts. ### Integrations diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index afb6d016f45..2e224208eb8 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- @@ -28,7 +28,6 @@ above the log file data, depending on your configuration: <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> To learn more about the Log Explorer, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). -NOTE: **Note:** [Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/). Everything you need to build, test, deploy, and run your application at scale. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 360b02efb69..c1e4e821efd 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -115,9 +115,7 @@ the components outlined above and the pre-loaded demo runbook. VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value ``` -1. To configure the operation of a runbook, create and configure variables: - - NOTE: **Note:** +1. To configure the operation of a runbook, create and configure variables. For this example, we are using the **Run SQL queries in Notebook** section in the sample runbook to query a PostgreSQL database. The first four lines of the following code block define the variables that are required for this query to function: diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index a15660051f7..bed01ff4d58 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -85,7 +85,7 @@ Host Security (Falco) are deployed with this model. To deploy GitLab Managed Apps to your cluster, you must first [add your cluster](add_remove_clusters.md) -to GitLab. Then [install](../../clusters/applications.md#installing-applications) +to GitLab. Then [install](../../clusters/applications.md#install-with-one-click) the Web Application Firewall from the project or group Kubernetes page. Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 543ffdbce8f..db91f78fc20 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -136,8 +136,8 @@ This example code does the following: In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**. For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#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. + The AWS credentials you provide must include IAM policies that provision correct + access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. #### Deploying your function @@ -154,9 +154,7 @@ endpoints: #### Manually testing your function Running the following `curl` command should trigger your function. - -NOTE: **Note:** -Your URL should be the one retrieved from the GitLab deploy stage log. +Your URL should be the one retrieved from the GitLab deploy stage log: ```shell curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello @@ -222,7 +220,8 @@ the environment of the deployed function: ```yaml provider: - ... + # Other configuration omitted + # ... environment: A_VARIABLE: ${env:A_VARIABLE} ``` @@ -245,10 +244,10 @@ functions: hello: handler: src/handler.hello events: - - http: # Rewrite this part to enable CORS + - http: # Rewrite this part to enable CORS path: hello method: get - cors: true # <-- CORS here + cors: true # <-- CORS here ``` You also need to return CORS specific headers in your function response: @@ -378,7 +377,6 @@ To set these: `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. -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. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 1157c2c5632..603c4bd73b1 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -75,8 +75,8 @@ To run Knative on GitLab, you will need: ## Installing Knative via GitLab's Kubernetes integration -NOTE: **Note:** -The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** +The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB +memory. **RBAC must be enabled.** 1. [Add a Kubernetes cluster](../add_remove_clusters.md). 1. Select the **Applications** tab and scroll down to the Knative app section. Enter the domain to be used with @@ -99,22 +99,19 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.  -NOTE: **Note:** You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) -on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project. +on a given project, but not both. The current implementation makes use of a +`serverless.yml` file to signal a FaaS project. ## Using an existing installation of Knative > [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 +The _invocations_ monitoring feature of GitLab serverless won't work when adding an existing installation of Knative. -It is also possible to use GitLab Serverless with an existing Kubernetes -cluster which already has Knative installed. - -You must do the following: +It's also possible to use GitLab Serverless with an existing Kubernetes cluster +which already has Knative installed. You must do the following: 1. Follow the steps to [add an existing Kubernetes @@ -453,16 +450,16 @@ To run a function locally: > Introduced in GitLab 11.5. +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Serverless applications are an alternative to [serverless functions](#deploying-functions). -They are useful in scenarios where an existing runtime does not meet the needs of an application, -such as one written in a language that has no runtime available. Note though that serverless -applications should be stateless! - -NOTE: **Note:** -You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. +They're useful in scenarios where an existing runtime does not meet the needs of +an application, such as one written in a language that has no runtime available. +Note though that serverless applications should be stateless. -Add the following `.gitlab-ci.yml` to the root of your repository -(you may skip this step if you've previously cloned the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above): +You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) +to get started. Add the following `.gitlab-ci.yml` to the root of your repository +(you may skip this step if you've previously cloned the previously mentioned, +sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app)): ```yaml include: @@ -561,14 +558,18 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. In order to serve over `https` you -must manually obtain and install TLS certificates. +By default, a GitLab serverless deployment will be served over `http`. To serve +over `https`, you must manually obtain and install TLS certificates. -The simplest way to accomplish this is to -use [Certbot to manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS. +12345678901234567890123456789012345678901234567890123456789012345678901234567890 +The simplest way to accomplish this is to use Certbot to +[manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). +Certbot is a free, open source software tool for automatically using Let’s Encrypt +certificates on manually-administered websites to enable HTTPS. -NOTE: **Note:** -The instructions below relate to installing and running Certbot on a Linux server that has Python 3 installed and may not work on other operating systems or with other versions of Python. +The following instructions relate to installing and running Certbot on a Linux +server that has Python 3 installed, and may not work on other operating systems +or with other versions of Python. 1. Install Certbot by running the [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto). @@ -788,7 +789,7 @@ The instructions below relate to installing and running Certbot on a Linux serve kubectl edit gateway knative-ingress-gateway --namespace knative-serving ``` - Update the gateway to include the following tls: section and configuration: + Update the gateway to include the following `tls:` section and configuration: ```shell tls: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index f56673e69b7..d0c5a24826a 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -58,9 +58,9 @@ relevant language. | Language | Implementation | |---|---| -| Go | [sourcegraph/lsif-go](https://github.com/sourcegraph/lsif-go) | -| JavaScript | [sourcegraph/lsif-node](https://github.com/sourcegraph/lsif-node) | -| TypeScript | [sourcegraph/lsif-node](https://github.com/sourcegraph/lsif-node) | +| Go | [`sourcegraph/lsif-go`](https://github.com/sourcegraph/lsif-go) | +| JavaScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | +| TypeScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | View a complete list of [available LSIF indexers](https://lsif.dev/#implementations-server) on their website and refer to their documentation to see how to generate an LSIF file for your specific language. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 730a9ada428..4ae3d5ec032 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -75,7 +75,6 @@ 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)** -NOTE: **Note:** Developer or higher [permissions](../permissions.md) are required in order to approve a merge request. @@ -93,12 +92,14 @@ to specify the actual owners and granular permissions. Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) 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 +changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as administrators don't have to restrict developers from pushing directly to the protected branch, but can restrict pushing to certain files where a review by Code Owners is required. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules, Code Owners included. + ## The syntax of Code Owners files Files can be specified using the same kind of patterns you would use @@ -158,7 +159,7 @@ file.md @group-x @group-x/subgroup-y ### Code Owners Sections **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better organization of broader categories of Code Owner rules to be applied. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8146f39ef87..3c6494d5f1a 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -85,7 +85,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you will need it - for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable). + for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and @@ -106,7 +106,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ be done automatically and no action is necessary. If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: - +  Once all of the above are set up and the pipeline has run at least once, diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 81c9008c5b3..4f344554016 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -12,7 +12,7 @@ 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. +fake user account. There are two types of deploy keys: diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index aa5987bf5f9..e0c4097d1c5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -49,8 +49,8 @@ To create a Markdown file: 1. Click the `+` button next to `master` and click **New file**. 1. Add the name of your issue template to the **File name** text field next to `master`. - Make sure words are separated with underscores and that your file has the `.md` extension, for - example `feature_request.md`. + Make sure that your file has the `.md` extension, for + example `feature_request.md` or `Feature Request.md`. 1. Commit and push to your default branch. If you don't have a `.gitlab/issue_templates` directory in your repository, you'll need to create it. @@ -79,6 +79,9 @@ This will enable the `Bug` dropdown option when creating or editing issues. When to the issue description field. The 'Reset template' button will discard any changes you made after picking the template and return it to its initial status. +TIP: **Tip:** +You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. +  ## Setting a default template for merge requests and issues **(STARTER)** diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 6fd33901621..46c2e211d57 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -69,7 +69,7 @@ brew install git-lfs ``` Once installed, **open your local repository in a terminal window** and -install Git LFS in your repo. If you're sure that LFS is already installed, +install Git LFS in your repository. If you're sure that LFS is already installed, you can skip this step. If you're unsure, re-installing it won't do any harm: ```shell @@ -159,7 +159,7 @@ command line interface, file locks can be created for any file. ### View exclusively-locked files To list all the files locked with LFS locally, open a terminal window in your -repo and run: +repository and run: ```shell git lfs locks @@ -189,7 +189,7 @@ Suggested workflow for shared projects: 1. Lock the file. 1. Edit the file. 1. Commit your changes. -1. Push to the repo. +1. Push to the repository. 1. Get your changes reviewed, approved, and merged. 1. Unlock the file. diff --git a/doc/user/project/img/issue_board_default_lists_v13_4.png b/doc/user/project/img/issue_board_default_lists_v13_4.png Binary files differnew file mode 100644 index 00000000000..23cdc9b4e22 --- /dev/null +++ b/doc/user/project/img/issue_board_default_lists_v13_4.png diff --git a/doc/user/project/img/issue_board_welcome_message.png b/doc/user/project/img/issue_board_welcome_message.png Binary files differdeleted file mode 100644 index 357dff42488..00000000000 --- a/doc/user/project/img/issue_board_welcome_message.png +++ /dev/null diff --git a/doc/user/project/img/labels_key_value_v12_1.png b/doc/user/project/img/labels_key_value_v12_1.png Binary files differdeleted file mode 100644 index ccda944a647..00000000000 --- a/doc/user/project/img/labels_key_value_v12_1.png +++ /dev/null diff --git a/doc/user/project/img/labels_key_value_v13_5.png b/doc/user/project/img/labels_key_value_v13_5.png Binary files differnew file mode 100644 index 00000000000..4264eb3211e --- /dev/null +++ b/doc/user/project/img/labels_key_value_v13_5.png diff --git a/doc/user/project/img/labels_prioritized_v12_1.png b/doc/user/project/img/labels_prioritized_v12_1.png Binary files differdeleted file mode 100644 index 512c5d59a5a..00000000000 --- a/doc/user/project/img/labels_prioritized_v12_1.png +++ /dev/null diff --git a/doc/user/project/img/labels_prioritized_v13_5.png b/doc/user/project/img/labels_prioritized_v13_5.png Binary files differnew file mode 100644 index 00000000000..04ffd67a59f --- /dev/null +++ b/doc/user/project/img/labels_prioritized_v13_5.png diff --git a/doc/user/project/img/labels_subscriptions_v12_1.png b/doc/user/project/img/labels_subscriptions_v12_1.png Binary files differdeleted file mode 100644 index fa83b7db414..00000000000 --- a/doc/user/project/img/labels_subscriptions_v12_1.png +++ /dev/null diff --git a/doc/user/project/img/labels_subscriptions_v13_5.png b/doc/user/project/img/labels_subscriptions_v13_5.png Binary files differnew file mode 100644 index 00000000000..a2a4e9e50cc --- /dev/null +++ b/doc/user/project/img/labels_subscriptions_v13_5.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 89130d5822f..56266718d12 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -76,6 +76,3 @@ If you've accidentally started the import process with the wrong account, follow 1. Revoke GitLab access to your Bitbucket account, essentially reversing the process in the following procedure: [Import your Bitbucket repositories](#import-your-bitbucket-repositories). 1. Sign out of the Bitbucket account. Follow the procedure linked from the previous step. - -NOTE: **Note:** -To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index d0499730bfe..ac5be2b46a4 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -37,12 +37,7 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. empty changes. 1. Attachments in Markdown are currently not imported. 1. Task lists are not imported. -1. Emoji reactions are not imported. -1. [LFS objects](../../../topics/git/lfs/index.md) are not imported. - - NOTE: **Note:** - To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. - +1. Emoji reactions are not imported 1. Project filtering does not support fuzzy search (only `starts with` or `full match strings` are currently supported) @@ -69,20 +64,43 @@ namespace that started the import process. #### User assignment by username -Alternatively, user assignment by username is available behind a `bitbucket_server_user_mapping_by_username` feature flag. -The importer will try to find a user in the GitLab user database using author's `username` or `slug` or `displayName`. -Falls back to author's `email` if user is not found by username. -Similarly to user assignment by email, if no such user is available, the project creator is set as the author. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +If you've enabled this feature, the importer tries to find a user in the GitLab user database with +the author's: + +- `username` +- `slug` +- `displayName` + +If the user is not found by any of these properties, the search falls back to the author's +`email` address. -To enable or disable user assignment by username: +Alternatively, if there is also no email address, the project creator is set as the author. -Start a [Rails console](../../../administration/troubleshooting/debug.md#starting-a-rails-console-session). +##### Enable or disable User assignment by username + +User assignment by username is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: ```ruby -# Enable Feature.enable(:bitbucket_server_user_mapping_by_username) +``` -# Disable +To disable it: + +```ruby Feature.disable(:bitbucket_server_user_mapping_by_username) ``` diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index f21ec26bdef..2d0caa7d46e 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -96,7 +96,7 @@ back to both GitLab and GitHub when completed. The mirroring is pull-only by default, so you may create or update the file on GitHub: -  +  1. Once your file has been committed, a new pipeline will be automatically triggered if your file is valid: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 4cd0c9e02c7..6c0105aaded 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -35,25 +35,20 @@ The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `git This process does not migrate or import any types of groups or organizations from GitHub to GitLab. -### If you're using GitLab.com +### Use cases -If you're using GitLab.com, you can alternatively import -GitHub repositories using a [personal access token](#using-a-github-token), -but we don't recommend this method because it can't associate all user activity -(such as issues and pull requests) with matching GitLab users. +The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. -### If you're importing from GitLab Enterprise - -If you're importing from GitHub Enterprise, you must enable [GitHub integration][gh-import]. - -### If you're using a self-managed GitLab instance - -If you're an administrator of a self-managed GitLab instance, you must enable -[GitHub integration][gh-import]. - -If you're an administrator of a self-managed GitLab instance, you can also use the -[GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects from -GitHub without the constraints of a Sidekiq worker. +- If you're importing to GitLab.com, you can alternatively import GitHub repositories + using a [personal access token](#using-a-github-token). We do not recommend + this method, as it does not associate all user activity (such as issues and + pull requests) with matching GitLab users. +- If you're importing to a self-managed GitLab instance, you can alternatively use the + [GitHub Rake task](../../../administration/raketasks/github_import.md) to import + projects without the constraints of a [Sidekiq](../../../development/sidekiq_style_guide.md) worker. +- If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable + [GitHub integration](../../../integration/github.md). However, you cannot import projects from GitHub Enterprise to GitLab.com. +- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. ## How it works @@ -106,7 +101,7 @@ If you are using a self-managed GitLab instance or if you are importing from Git 1. From the top navigation bar, click **+** and select **New project**. 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. -1. Click **Authorize gitlabhq**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Click **Authorize GitlabHQ**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. 1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token @@ -124,7 +119,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Go to <https://github.com/settings/tokens/new> 1. Enter a token description. -1. Select the repo scope. +1. Select the repository scope. 1. Click **Generate token**. 1. Copy the token hash. 1. Go back to GitLab and provide the token to the GitHub importer. @@ -141,10 +136,10 @@ your GitHub repositories are listed. 1. Select the **Import** button next to any number of repositories, or select **Import all repositories**. Additionally, you can filter projects by name. If filter is applied, **Import all repositories** only imports matched repositories. 1. The **Status** column shows the import status of each repository. You can choose to leave the page open and it will - update in realtime or you can return to it later. + update in real-time or you can return to it later. 1. Once a repository has been imported, click its GitLab path to open its GitLab URL. - + ## Mirroring and pipeline status sharing @@ -154,7 +149,7 @@ your imported repository in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the [GitHub Project Integration](../integrations/github.md). **(PREMIUM)** -If you import your project using [CI/CD for external repo](../../../ci/ci_cd_for_external_repos/index.md), then both +If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both of the above are automatically configured. **(PREMIUM)** ## Improving the speed of imports on self-managed instances diff --git a/doc/user/project/import/img/manifest_status_v13_3.png b/doc/user/project/import/img/manifest_status_v13_3.png Binary files differindex 3f0063e6715..c1a55ba1f50 100644 --- a/doc/user/project/import/img/manifest_status_v13_3.png +++ b/doc/user/project/import/img/manifest_status_v13_3.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 86b671c8371..a1c28cfa2b7 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -18,7 +18,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 1. [From Perforce](perforce.md) 1. [From SVN](svn.md) 1. [From TFVC](tfvc.md) -1. [From repo by URL](repo_by_url.md) +1. [From repository by URL](repo_by_url.md) 1. [By uploading a manifest file (AOSP)](manifest.md) 1. [From Gemnasium](gemnasium.md) 1. [From Phabricator](phabricator.md) @@ -32,7 +32,7 @@ There is also the option of [connecting your external repository to get CI/CD be ## Migrating from self-managed GitLab to GitLab.com -If you only need to migrate Git repos, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. +If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. If you want to retain all metadata like issues and merge requests, you can use the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 60524f3cc69..ba1e2011d08 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -56,7 +56,7 @@ You can start the import with: 1. From your GitLab dashboard click **New project** 1. Switch to the **Import project** tab 1. Click on the **Manifest file** button -1. Provide GitLab with a manifest xml file +1. Provide GitLab with a manifest XML file 1. Select a group you want to import to (you need to create a group first if you don't have one) 1. Click **List available repositories**. At this point, you will be redirected to the import status page with projects list based on the manifest file. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index dbc1c491493..4ccc34efe30 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -20,7 +20,7 @@ Git: it creates an integration record in their proprietary database for every file in the branch, regardless how many were actually changed. Whereas Git was implemented with a different architecture so that a single SHA acts as a pointer - to the state of the whole repo after the changes, making it very easy to branch. + to the state of the whole repository after the changes, making it very easy to branch. This is what made feature branching workflows so easy to adopt with Git. 1. Also, context switching between branches is much easier in Git. If your manager said 'You need to stop work on that new feature and fix this security diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 9b5e43aae79..5c53b6eaf06 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -5,7 +5,7 @@ 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 +# Import project from repository by URL You can import your existing repositories by providing the Git URL: @@ -16,4 +16,4 @@ You can import your existing repositories by providing the Git URL: 1. Click **Create project** to begin the import process 1. Once complete, you will be redirected to your newly created project - + diff --git a/doc/user/project/index.md b/doc/user/project/index.md index c79f2be1d3f..a00f93bac9c 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -34,7 +34,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Protected tags](protected_tags.md): Control over who has permission to create tags, and prevent accidental update or deletion - [Repository mirroring](repository/repository_mirroring.md) - - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits + - [Signing commits](repository/gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a @@ -96,9 +96,9 @@ When you create a project in GitLab, you'll have access to a large number of - [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. - [Snippets](../snippets.md): store, share and collaborate on code snippets. -- [Value Stream Analytics](cycle_analytics.md): review your development lifecycle. +- [Value Stream Analytics](../analytics/value_stream_analytics.md): review your development lifecycle. - [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** -- [Security Dashboard](security_dashboard.md): Security Dashboard. **(ULTIMATE)** +- [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** - [Syntax highlighting](highlighting.md): an alternative to customize your code blocks, overriding GitLab's default choice of language. - [Badges](badges.md): badges for the project overview. diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 443ca11be27..bb4a5b2b97f 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -14,8 +14,8 @@ See the project homepage for further information: <https://gitlab.com/esr/irker> ## Needed setup -You will first need an Irker daemon. You can download the Irker code from its -repository on <https://gitlab.com/esr/irker>: +You will first need an Irker daemon. You can download the Irker code +[from its repository](https://gitlab.com/esr/irker): ```shell git clone https://gitlab.com/esr/irker.git @@ -55,6 +55,6 @@ case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append `?key=thesecretpassword` to the channel name. When using this feature remember to **not** put the `#` sign in front of the channel name; failing to do so will -result on irker joining a channel literally named `#chan?key=password` henceforth +result on Irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server -configuration). This is due to a long standing irker bug. +configuration). This is due to a long standing Irker bug. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 3e0b6492477..b4e02bbd5f3 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -23,7 +23,7 @@ Features include: - **View a list of Jira issues directly in GitLab** **(PREMIUM)** For additional features, you can install the -[Jira Development Panel integration](../../../integration/jira_development_panel.md) **(PREMIUM)**. +[Jira Development Panel integration](../../../integration/jira_development_panel.md). This enables you to: - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. @@ -122,6 +122,8 @@ By now you should have [configured Jira](#configuring-jira) and enabled the you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. +Jira issue IDs must be formatted in uppercase for the integration to work. + ### Reference Jira issues When GitLab project has Jira issue tracker configured and enabled, mentioning diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 7a1f757c138..a502dfbf320 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -50,7 +50,7 @@ Click on the service links to see further configuration instructions and details | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | No | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | No | | [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | No | -| Packagist | Update your project on Packagist, the main Composer repository | Yes | +| Packagist | Update your projects on Packagist, the main Composer repository | Yes | | Pipelines emails | Email the pipeline status to a list of recipients | No | | [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | | [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | No | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index a19b819c823..28a9afa5bb0 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- @@ -58,6 +58,43 @@ CPU and Memory consumption is monitored, but requires [naming conventions](prome The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed by GitLab to clusters, is automatically annotated for monitoring providing key response metrics: latency, throughput, and error rates. +##### Example of Kubernetes service annotations and labels + +As an example, to activate Prometheus monitoring of a service: + +1. Add at least this annotation: `prometheus.io/scrape: 'true'`. +1. Add two labels so GitLab can retrieve metrics dynamically for any environment: + - `application: ${CI_ENVIRONMENT_SLUG}` + - `release: ${CI_ENVIRONMENT_SLUG}` +1. Create a dynamic PromQL query. For example, a query like + `temperature{application="{{ci_environment_slug}}",release="{{ci_environment_slug}}"}` to either: + - Add [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). + - Add [custom dashboards](../../../operations/metrics/dashboards/index.md). + +The following is a service definition to accomplish this: + +```yaml +--- +# Service +apiVersion: v1 +kind: Service +metadata: + name: service-${CI_PROJECT_NAME}-${CI_COMMIT_REF_SLUG} + # === Prometheus annotations === + annotations: + prometheus.io/scrape: 'true' + labels: + application: ${CI_ENVIRONMENT_SLUG} + release: ${CI_ENVIRONMENT_SLUG} + # === End of Prometheus === +spec: + selector: + app: ${CI_PROJECT_NAME} + ports: + - port: ${EXPOSED_PORT} + targetPort: ${CONTAINER_PORT} +``` + ### Manual configuration of Prometheus #### Requirements @@ -136,10 +173,7 @@ one of them will be used: > - 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. - -NOTE: **Note:** -Requires [Kubernetes](prometheus_library/kubernetes.md) metrics. +request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and numeric comparison of the average memory consumption will appear. On the diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index e278c7eb664..70f8a55bb07 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 712805b75f2..0fbc49ddad7 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 6f2c2477eee..35b111ab2b2 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 29efe08e53d..43c2d305437 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- @@ -12,7 +12,7 @@ GitLab has support for automatically detecting and monitoring Kubernetes metrics ## Requirements -The [Prometheus](../prometheus.md) and [Kubernetes](../kubernetes.md) +The [Prometheus](../prometheus.md) and [Kubernetes](../../clusters/index.md) integration services must be enabled. ## Metrics supported diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 0d3042463c9..1757378fb70 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 7bebe7b1e65..fdea800c410 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- @@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. +GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. + NOTE: **Note:** NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. -GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. - ## Requirements [Prometheus integration](../prometheus.md) must be active. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 326931e9790..ec7b1ee6d10 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +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 --- diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 688643a85a7..abb072c9a0a 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -6,20 +6,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Service templates -Using a service template, GitLab administrators can provide default values for configuring integrations at the project level. +Using a service template, GitLab administrators can: -When you enable a service template, the defaults are applied to **all** projects that do not -already have the integration enabled or do not otherwise have custom values saved. -The values are pre-filled on each project's configuration page for the applicable integration. +- Provide default values for configuring integrations when creating new projects. +- Bulk configure all existing projects in one step. -If you disable the template, these values no longer appear as defaults, while -any values already saved for an integration remain unchanged. +When you enable a service template: + +- The defaults are applied to **all** existing projects that either: + - Don't already have the integration enabled. + - Don't have custom values stored for already enabled integrations. +- Values are populated on each project's configuration page for the applicable + integration. +- Settings are stored at the project level. + +If you disable the template: + +- GitLab default values again become the default values for integrations on + new projects. +- Projects previously configured using the template will continue to use + those settings. + +If you change the template, the revised values are applied to new projects. This feature +does not provide central administration of integration settings. + +## Central administration of project integrations + +A new set of features is being introduced in GitLab to provide more control over +how integrations are configured at the instance, group, and project level. + +[Read more about setting up project integration management](../../admin_area/settings/project_integration_management.md) +(introduced in GitLab 13.3) and [our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Enable a service template Navigate to the **Admin Area > Service Templates** and choose the service template you wish to create. +Recommendation: + +- Test the settings on some projects individually before enabling a template. +- Copy the working settings from a project to the template. + +There is no "Test settings" option when enabling templates. If the settings do not work, +these incorrect settings will be applied to all existing projects that do not already have +the integration configured. Fixing the integration then needs to be done project-by-project. + ## Service for external issue trackers The following image shows an example service template for Redmine. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 03ff5f845b6..e6f12c2532f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -64,7 +64,7 @@ The following triggers are available for Slack notifications: - **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. +- **Deployment**: Triggered when a deployment starts or finishes. - **Alert**: Triggered when a new, unique alert is recorded. ## Troubleshooting diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 800eb1d3359..7adea5ebcd6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1303,7 +1303,12 @@ Note that `commit.id` is the ID of the pipeline, not the ID of the commit. ### Deployment events -Triggered when deployment is finished/failed/canceled. +Triggered when a deployment: + +- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) +- Succeeds +- Fails +- Is cancelled **Request Header**: diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index f8172a0f988..bce40e9a838 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -8,14 +8,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [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). -## Overview - The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. -It pairs issue tracking and project management, keeping everything in the same place, +It pairs issue tracking and project management, keeping everything together, so that you don't need to jump between different platforms to organize your workflow. Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and @@ -26,8 +24,8 @@ Issue boards help you to visualize and manage your entire process in GitLab. You add your labels, and then create the corresponding list for your existing issues. When you're ready, you can drag your issue cards from one step to another one. -An issue board can show you what issues your team is working on, who is assigned to each, -and where in the workflow those issues are. +An issue board can show you the issues your team is working on, who is assigned to each, +and where the issues are in the workflow. To let your team members organize their own workflows, use [multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue @@ -60,8 +58,8 @@ Here are some common use cases for issue boards. ### Use cases for a single issue board -With the GitLab Workflow you can discuss proposals in issues, categorize them -with labels, and from there, organize and prioritize them with issue boards. +With the GitLab Workflow you can discuss proposals in issues, label +them, and organize and prioritize them with issue boards. For example, let's consider this simplified development workflow: @@ -155,7 +153,7 @@ card includes: ## Permissions Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the -Issue Board feature to create or delete lists and drag issues from one list to another. +Issue Board feature to create or delete lists. They can also drag issues from one list to another. ## How GitLab orders issues in a list @@ -164,20 +162,19 @@ that order by dragging the issues. The changed order is saved, so that anybody w board later sees the reordering, with some exceptions. The first time a given issue appears in any board (that is, the first time a user -loads a board containing that issue), it is ordered in relation to other issues in that list -according to [label priority](labels.md#label-priority). +loads a board containing that issue), it is ordered in relation to other issues in that list. +The order is done according to [label priority](labels.md#label-priority). At this point, that issue is assigned a relative order value by the system, -representing its relative order with respect to the other issues in the list. Any time -you reorder that issue by dragging, its relative order value changes accordingly. +with respect to the other issues in the list. Any time +you drag and reorder the issue, its relative order value changes accordingly. -Also, any time that issue appears in any board when it's loaded by a user, -the updated relative order value is used for the ordering. It's only the first -time an issue appears that it takes from the priority order mentioned above. This means that -if issue `A` is reordered by dragging to be above issue `B` by any user in -a given board inside your GitLab instance, any time those two issues are subsequently -loaded in any board in the same instance (could be a different project board or a different group -board, for example), that ordering is maintained. +Also, any time that issue appears in any board, the ordering is done according to +the updated relative order value. It's only the first +time an issue appears that it takes from the priority order mentioned above. If a user in your GitLab instance +drags issue `A` above issue `B`, the ordering is maintained when these two issues are subsequently +loaded in any board in the same instance. This could be a different project board or a different group +board, for example. This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, @@ -195,8 +192,7 @@ advanced functionality is present in [higher tiers only](https://about.gitlab.co > - 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. -This is great for large projects with more than one team or in situations where a repository is used -to host the code of multiple products. +This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -230,13 +226,13 @@ To delete the currently active issue board: An issue board can be associated with a GitLab [Milestone](milestones/index.md#milestones), [Labels](labels.md), Assignee and Weight -which will automatically filter the Board issues according to these fields. +which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need.  You can define the scope of your board when creating it or by clicking the "Edit board" button. -Once a milestone, assignee or weight is assigned to an issue board, you will no longer be able to +Once a milestone, assignee or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. @@ -274,24 +270,22 @@ especially in combination with [assignee lists](#assignee-lists). ### Group issue boards **(PREMIUM)** -> [Introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. +> - One group issue board per group introduced in GitLab 10.6. +> - Multiple group issue boards [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. -Accessible at the group navigation level, a group issue board offers the same features as a project-level board, -but it can display issues from all projects in that +Accessible at the group navigation level, a group issue board offers the same features as a project-level board. +It can display issues from all projects in that group and its descendant subgroups. Similarly, you can only filter by group labels for these boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only group-level objects are available. -NOTE: **Note:** -Multiple group issue boards were originally [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0, and one group issue board per group was made available in GitLab Core 10.6. -  ### Assignee lists **(PREMIUM)** > [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 +As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists. To add an assignee list: @@ -317,7 +311,7 @@ milestone, giving you more freedom and visibility on the issue board. To add a m 1. Select the **Milestone** tab. 1. Search and click the milestone. -Similar to the assignee lists, you're now able to [drag issues](#drag-issues-between-lists) +Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists) to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. @@ -333,7 +327,7 @@ You cannot set a WIP limit on the default lists (**Open** and **Closed**). Examples: -- You have a list with four issues, and a limit of five, the header will show **4/5**. +- When you have a list with four issues and a limit of five, the header shows **4/5**. If you exceed the limit, the current number of issues is shown in red. - You have a list with five issues with a limit of five. When you move another issue to that list, the list's header displays **6/5**, with the six shown in red. @@ -374,29 +368,24 @@ If you're not able to do some of the things above, make sure you have the right ### First time using an issue board -The first time you open an issue board, you are presented with -the default lists (**Open** and **Closed**) and a welcome message that gives -you two options. You can either: +> The automatic creation of the **To Do** and **Doing** lists was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. -- Create a predefined set of labels (by default: **To Do** and **Doing**) and create their - corresponding lists to the issue board. -- Opt-out and use your own lists. +The first time you open an issue board, you are presented with the default lists +(**Open**, **To Do**, **Doing**, and **Closed**). - +If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and +their lists appear as empty. If any of them already exists, the list is filled with the issues that +have that label. -If you choose to use and create the predefined lists, they will appear as empty -because the labels associated to them will not exist up until that moment, -which means the system has no way of populating them automatically. That's of -course if the predefined labels don't already exist. If any of them does exist, -the list will be created and filled with the issues that have that label. + ### Create a new list Create a new list by clicking the **Add list** button in the upper right corner of the issue board. - + -Then, choose the label or user to create the list from. The new list will be inserted +Then, choose the label or user to create the list from. The new list is inserted at the end of the lists, before **Done**. Moving and reordering lists is as easy as dragging them around. @@ -407,15 +396,15 @@ You can now choose it to create a list. ### Delete a list To delete a list from the issue board, use the small trash icon present -in the list's heading. A confirmation dialog will appear for you to confirm. +in the list's heading. A confirmation dialog appears for you to confirm. -Deleting a list doesn't have any effect in issues and labels, it's just the -list view that is removed. You can always add it back later if you need. +Deleting a list doesn't have any effect on issues and labels, as it's just the +list view that's removed. You can always restore it later if you need. ### Add issues to a list You can add issues to a list by clicking the **Add issues** button -present in the upper right corner of the issue board. This will open up a modal +present in the upper right corner of the issue board. This opens up a modal window where you can see all the issues that do not belong to any list. Select one or more issues by clicking the cards and then click **Add issues** @@ -435,7 +424,7 @@ respective label is removed. ### Filter issues You should be able to use the filters on top of your issue board to show only -the results you want. This is similar to the filtering used in the issue tracker +the results you want. It's similar to the filtering used in the issue tracker since the metadata from the issues and labels are re-used in the issue board. You can filter by author, assignee, milestone, and label. @@ -469,12 +458,12 @@ For example, you can create a list based on the label of **Frontend** and one fo worked on by the designers. Then, once they're done, all they have to do is -drag it to the next list, **Backend**, where a backend developer can +drag it to the next list, **Backend**. Then, a backend developer can eventually pick it up. Once they’re done, they move it to **Done**, to close the issue. -This process can be seen clearly when visiting an issue since with every move -to another list the label changes and a system note is recorded. +This process can be seen clearly when visiting an issue. With every move +to another list, the label changes and a system note is recorded.  diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index c721bef8f4d..2a75f8ad837 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -33,7 +33,7 @@ Of course, you can replace `gitlab.com` with the URL of your own GitLab instance NOTE: **Note:** Linking your first commit to your issue is going to be relevant -for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). It will measure the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 7c9278c8403..6f57487fccd 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -4,14 +4,12 @@ group: Knowledge 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" --- -# Design Management +# Design Management **(CORE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. -## Overview - Design Management allows you to upload design assets (wireframes, mockups, etc.) to GitLab issues and keep them stored in one single place, accessed by the Design Management's page within an issue, giving product designers, product managers, and engineers a @@ -58,8 +56,7 @@ Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned - From GitLab 13.1, Design filenames are limited to 255 characters. - 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) +- Design Management data [won't be 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). @@ -114,9 +111,6 @@ Designs with the same filename as an existing uploaded design will create a new 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 -[discussion is locked](../../discussions/#lock-discussions). - ### Skipped designs Designs with the same filename as an existing uploaded design _and_ whose content has not changed will be skipped. @@ -185,9 +179,7 @@ viewed by browsing previous versions. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. -You can change the order of designs by dragging them to a new position: - - +You can change the order of designs by dragging them to a new position. ## Starting discussions on designs @@ -231,47 +223,19 @@ Note that your resolved comment pins will disappear from the Design to free up s However, if you need to revisit or find a resolved discussion, all of your resolved threads will be available in the **Resolved Comment** area at the bottom of the right sidebar. -## Add To-Do for Designs +## Add to dos for designs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-design-to-do-button). **(CORE ONLY)** - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. - -Add a to-do for a design by clicking **Add a To-Do** on the design sidebar: - - - -### Enable or disable the design To-Do button **(CORE ONLY)** - -The **Add a To-Do** button for Designs is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:design_management_todo_button) -``` +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -To disable it: +Add a to do for a design by clicking **Add a To Do** on the design sidebar: -```ruby -Feature.disable(:design_management_todo_button) -``` + ## 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)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in **GitLab 13.5** 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. @@ -287,25 +251,6 @@ 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 -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:design_management_reference_filter_gfm_pipeline) -``` - -To re-enable it: - -```ruby -Feature.enable(:design_management_reference_filter_gfm_pipeline) -``` - ## Design activity records > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33051) in GitLab 13.1. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 55b45bf9d3d..b3ebefadef0 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -46,7 +46,7 @@ the icon and the date colored red. You can sort issues by those that are Due dates also appear in your [to-do list](../../todos.md). - + The day before an open issue is due, an email will be sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the diff --git a/doc/user/project/issues/img/design_todo_button_v13_4.png b/doc/user/project/issues/img/design_todo_button_v13_4.png Binary files differdeleted file mode 100644 index 62bbecf4ed9..00000000000 --- a/doc/user/project/issues/img/design_todo_button_v13_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_todo_button_v13_5.png b/doc/user/project/issues/img/design_todo_button_v13_5.png Binary files differnew file mode 100644 index 00000000000..970161a6097 --- /dev/null +++ b/doc/user/project/issues/img/design_todo_button_v13_5.png diff --git a/doc/user/project/issues/img/designs_reordering_v13_3.gif b/doc/user/project/issues/img/designs_reordering_v13_3.gif Binary files differdeleted file mode 100644 index 496eea532e2..00000000000 --- a/doc/user/project/issues/img/designs_reordering_v13_3.gif +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 060266a478f..434af3a4a49 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -156,12 +156,15 @@ collaborate with your team. efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones. -### Related issues **(STARTER)** +### Related issues You can mark two issues as related, so that when viewing one, the other is always listed in its [Related Issues](related_issues.md) section. This can help display important context, such as past work, dependencies, or duplicates. +Users on [GitLab Starter, GitLab Bronze, and higher tiers](https://about.gitlab.com/pricing/), can +also mark issues as blocking or blocked by another issue. + ### Crosslinking issues You can [cross-link issues](crosslinking_issues.md) by referencing an issue from another diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 5356e6aeb40..003444e0ed8 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -36,7 +36,7 @@ You can find all the information for that issue on one screen. - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) -- **18.** [Related Issues **(STARTER)**](#related-issues) +- **18.** [Related Issues](#related-issues) - **19.** [Related Merge Requests](#related-merge-requests) - **20.** [Award emoji](#award-emoji) - **21.** [Show all activity](#show-all-activity) @@ -80,7 +80,7 @@ The button to do this has a different label depending on whether the issue is al List or not. If the issue is: - Already on your To-Do List: The button is labeled **Mark as done**. Click the button to remove the issue from your To-Do List. -- Not on your To-Do List: The button is labeled **Add a To Do**. Click the button to add the issue to your To-Do List. +- Not on your To-Do List: The button is labeled **Add a to do**. Click the button to add the issue to your To-Do List. ### Assignee @@ -191,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)** +> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** ### Mentions @@ -208,7 +208,7 @@ TIP: **Tip:** Avoid mentioning `@all` in issues and merge requests, as it sends an email notification to all the members of that project's group, which can be interpreted as spam. -### Related Issues **(STARTER)** +### Related Issues Issues that were mentioned as [related issues](related_issues.md) are listed here. You can also click the `+` to add more related issues. @@ -242,7 +242,7 @@ and selecting either: Also: - You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they will be notified via To-Do items + `@username` or `@groupname` and they will be notified via to-do items and email, unless they have [disabled all notifications](#notifications) in their profile settings. - Mentions for yourself (the current logged in user), will be highlighted diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 0e0731528be..b033dc79dcc 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -127,6 +127,7 @@ field). | title | `issue[title]` | | | description | `issue[description]` | | | description template | `issuable_template` | | +| issue type | `issue[issue_type]` | Either `incident` or `issue` | | confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential | Follow these examples to form your new issue URL with prefilled fields. diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index c11977f5bee..b1806460c08 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -8,8 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [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 - In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who didn't even start yet. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 954e3771722..b040bcf3b03 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,33 +4,40 @@ 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)** +# Related issues **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. +> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. Related issues are a bi-directional relationship between any two issues and appear in a block below the issue description. Issues can be across groups and projects. +You can set any issue as: + +- Related to another issue +- Blocking another issue **(STARTER)** +- Blocked by another issue **(STARTER)** + The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. TIP: **Tip:** -To manage related issues through our API, see the [API documentation](../../../api/issue_links.md). +To manage related issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). ## Adding a related issue > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2035) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. -> When you try to close an issue with open blockers, you'll see a warning that you can dismiss. +> When you try to close an issue with open blockers, you see a warning that you can dismiss. 1. Relate one issue to another by clicking the related issues "+" button in the header of the related issue block. 1. Input the issue reference number or paste in the full URL of the issue. -1. Select whether the current issue relates to, blocks, or is blocked by the issues being entered. +1. **(STARTER)** Select whether the current issue relates to, blocks, or is blocked by the issues being entered.  @@ -42,11 +49,11 @@ in the header of the related issue block. - same group: `project#44` - different group: `group/project#44` - Valid references will be added to a temporary list that you can review. + Valid references are added to a temporary list that you can review. 1. When you have added all the related issues, click **Add** to submit. -When you have finished adding all related issues, you will be able to see +When you have finished adding all related issues, you can see them categorized so their relationships can be better understood visually.  @@ -56,7 +63,7 @@ them categorized so their relationships can be better understood visually. In the related issues block, click the "x" icon on the right-side of each issue token that you wish to remove. -Due to the bi-directional relationship, it will no longer appear in either issue. +Due to the bi-directional relationship, it no longer appears in either issue.  diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 0d02b89be7e..4f0354f86af 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Labels -## Overview - As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging to keep track of those items. Especially as your organization grows from just a few people to hundreds or thousands. This is where labels come in. They help you organize and tag your work @@ -32,18 +30,25 @@ There are two types of labels in GitLab: ## Assign and unassign labels -Every issue, merge request and epic can be assigned any number of labels. The labels are +> Unassigning labels with the **X** button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216881) in GitLab 13.5. + +Every issue, merge request, and epic can be assigned any number of labels. The labels are managed in the right sidebar, where you can assign or unassign labels as needed. -To assign a label to an issue, merge request or epic: +To assign or unassign a label: -1. In the label section of the sidebar, click **Edit**, then: - - In the list, click the labels you want. Each label is flagged with a checkmark. - - Find labels by entering a search query and clicking search (**{search}**), then - click on them. You can search repeatedly and add more labels. -1. Click **X** or anywhere outside the label section and the labels are applied. +1. In the **Labels** section of the sidebar, click **Edit**. +1. In the **Assign labels** list, search for labels by typing their names. + You can search repeatedly to add more labels. + The selected labels are marked with a checkmark. +1. Click the labels you want to assign or unassign. +1. To apply your changes to labels, click **X** next to **Assign labels** or anywhere outside the + label section. -You can also assign a label with the [`/label ~label1 ~label2` quick action](quick_actions.md). +Alternatively, to unassign a label, click the **X** on the label you want to unassign. + +You can also assign a label with the `/label` [quick action](quick_actions.md), +remove labels with `/unlabel`, and reassign labels (remove all and assign new ones) with `/relabel`. ## Label management @@ -52,10 +57,13 @@ and edit labels. ### Project labels -View the project labels list by going to the project and clicking **Issues > Labels**. +> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in 13.5. + +To view the project labels list, navigate to the project and click **Issues > Labels**. The list includes all labels that are defined at the project level, as well as all -labels inherited from the immediate parent group. You can filter the list by entering a search -query at the top and clicking search (**{search}**). +labels defined by its ancestor groups. +For each label, you can see the project or group path from where it was created. +You can filter the list by entering a search query at the top and clicking search (**{search}**). To create a new project label: @@ -83,19 +91,19 @@ a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** and selecting **Delete**. CAUTION: **Caution:** -If you delete a label, it is permanently deleted. You will not be able to undo the deletion, and all references to the label will be removed from the system. +If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. #### Promote a project label to a group label If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label. -If other projects in the same group have a label with the same title, they will all be -merged with the new group label. If a group label with the same title exists, it will -also be merged. +If other projects in the same group have a label with the same title, they are all +merged with the new group label. If a group label with the same title exists, it is +also merged. All issues, merge requests, issue board lists, issue board filters, and label subscriptions -with the old labels will be assigned to the new group label. +with the old labels are assigned to the new group label. CAUTION: **Caution:** Promoting a label is a permanent action, and cannot be reversed. @@ -108,7 +116,7 @@ To promote a project label to a group label: ### Group labels -View the group labels list by going to the group and clicking **Issues > Labels**. +To view the group labels list, navigate to the group and click **Issues > Labels**. The list includes all labels that are defined at the group level only. It does not list any labels that are defined in projects. You can filter the list by entering a search query at the top and clicking search (**{search}**). @@ -118,15 +126,15 @@ follow the same process as [creating a project label](#project-labels). #### Create group labels from epics **(ULTIMATE)** -You can create group labels from the Epic sidebar. The labels you create will +You can create group labels from the epic sidebar. The labels you create belong to the immediate group to which the epic belongs. The process is the same as creating a [project label from an issue or merge request](#project-labels). ### Generate default labels If a project or group has no labels, you can generate a default set of project or group -labels from the label list page. The page will show a **Generate a default set of labels** -button if the list is empty, and clicking it will add the following default labels +labels from the label list page. The page shows a **Generate a default set of labels** +button if the list is empty. Select the button to add the following default labels to the project: - `bug` @@ -149,13 +157,13 @@ by preventing certain labels from being used together. A label is scoped when it uses a special double-colon (`::`) syntax in the label’s title, for example: - + An issue, merge request or epic cannot have two scoped labels, of the form `key::value`, -with the same `key`. Adding a new label with the same `key`, but a different `value` will -cause the previous `key` label to be replaced with the new label. +with the same `key`. Adding a new label with the same `key`, but a different `value` +causes the previous `key` label to be replaced with the new label. -Example use case: +For example: 1. An issue is identified as being low priority, and a `priority::low` project label is added to it. @@ -188,7 +196,7 @@ This functionality is demonstrated in a video regarding ### Scoped labels with nested scopes You can create a label with a nested scope by using multiple double colons `::` when creating -it. In this case, everything before the last `::` will be the scope. +it. In this case, everything before the last `::` is the scope. For example, `workflow::backend::review` and `workflow::backend::development` are valid scoped labels, but they **can't** exist on the same issue at the same time, as they @@ -202,13 +210,13 @@ both have different scopes, `workflow::frontend` and `workflow::backend`. From the project label list page and the group label list page, you can click **Subscribe** to the right of any label to enable [notifications](../profile/notifications.md) for that -label. You will be notified whenever the label is assigned to an epic, +label. You are notified whenever the label is assigned to an epic, issue, or merge request. If you are subscribing to a group label from within a project, you can select to subscribe to label notifications for the project only, or the whole group. - + ## Label priority @@ -222,7 +230,7 @@ from the group label list. From the project label list page, star a label to indicate that it has a priority. - + Drag starred labels up and down the list to change their priority, where higher in the list means higher priority. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index f3a0aac9ff4..a07a155745e 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -55,7 +55,7 @@ include: ``` creates an `a11y` job in your CI/CD pipeline, runs -Pa11y against the webpages defined in `a11y_urls`, and builds an HTML report for each. +Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts). diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 60d247ccc19..4ba0b50a3cf 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -28,11 +28,12 @@ source project and only lasts while the merge request is open. Once enabled, upstream members will also be able to retry the pipelines and jobs of the merge request: -1. Enable the contribution while creating or editing a merge request. +1. While creating or editing a merge request, select the checkbox **Allow + commits from members who can merge to the target branch**.  -1. Once the merge request is created, you'll see that commits from members who +1. Once the merge request is created, you can see that commits from members who can merge to the target branch are allowed.  diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index a0be32e0708..462b8f68ece 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -111,6 +111,48 @@ It is also possible to manage multiple assignees: - When creating a merge request. - Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +## Reviewer + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Requesting a code review is an important part of contributing code. However, deciding who should review +your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and +reviewers makes it hard for others to determine who's doing what on a merge request. + +GitLab's Merge Request Reviewers easily allow authors to request a review as well as see the status of the +review. By selecting one or more users from the **Reviewers** field in the merge request's right-hand +sidebar, the assigned reviewers will receive a notification of the request to review the merge request. + +This makes it easy to determine the relevant roles for the users involved in the merge request, as well as formally requesting a review from a peer. + +To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. + +### Enable or disable Merge Request Reviewers **(CORE ONLY)** + +Merge Request Reviewers is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:merge_request_reviewers) +``` + +To disable it: + +```ruby +Feature.disable(:merge_request_reviewers) +``` + ### Merge requests to close issues If the merge request is being created to resolve an issue, you can diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_4.png b/doc/user/project/merge_requests/img/commit_nav_v13_4.png Binary files differnew file mode 100644 index 00000000000..0ae6ce32693 --- /dev/null +++ b/doc/user/project/merge_requests/img/commit_nav_v13_4.png diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index daebd71e14f..2675f509eed 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -164,8 +164,8 @@ For example: 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). 1. In the `load_performance` job: - 1. Set it to depend on the review job, so it inherits the env file. - 1. Set the `K6_DOCKER_OPTIONS` variable with the [Docker cli option for env files](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file), for example `--env-file review.env`. + 1. Set it to depend on the review job, so it inherits the environment file. + 1. Set the `K6_DOCKER_OPTIONS` variable with the [Docker CLI option for environment files](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file), for example `--env-file review.env`. 1. Configure the k6 test script to use the environment variable in it's steps. Your `.gitlab-ci.yml` file might be similar to: diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 185ab0e6298..4b4c930c7af 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -5,13 +5,16 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge Request Approvals +# Merge Request Approvals **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Core and higher tiers. +> - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. Code review is an essential practice of every successful project, and giving your approval once a merge request is in good shape is an important part of the review process, as it clearly communicates the ability to merge the change. -## Optional Approvals **(CORE ONLY)** +## Optional Approvals > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. @@ -335,26 +338,6 @@ of your security team when a vulnerability would be introduced by a merge reques For more information, see [Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests). -### Enabling the new approvals interface - -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. - -Use these commands to start the Rails console: - -```shell -# Omnibus GitLab -gitlab-rails console - -# Installation from source -cd /home/git/gitlab -sudo -u git -H bin/rails console -e production -``` - -Then run `Feature.enable(:approval_rules)` to enable the updated interface. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index bc4fee749e8..6b302b0ff02 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -14,7 +14,7 @@ by clicking the **Revert** button in merge requests and commit details. NOTE: **Note:** The **Revert** button will only be available for merge requests -created since GitLab 8.5. However, you can still revert a merge request +created in GitLab 8.5 and later. However, you can still revert a merge request by reverting the merge commit from the list of Commits page. NOTE: **Note:** 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 3a18cacde64..aef68e0e771 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 @@ -84,7 +84,7 @@ Click **Expand file** on any file to view the changes for that file. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation). For larger merge requests it might sometimes be useful to review single files at a time. To enable, -from your avatar on the top-right navbar, click **Settings**, and go to **Preferences** on the left +from your avatar on the top-right navigation bar, click **Settings**, and go to **Preferences** on the left sidebar. Scroll down to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. Click **Save changes** to apply. @@ -122,6 +122,8 @@ the commits to open the single-commit view. From there, you can navigate among t by clicking the **Prev** and **Next** buttons on the top-right of the page or by using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + ### Incrementally expand merge request diffs By default, the diff shows only the parts of a file which are changed. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 69a0dd6e84f..68f5478038a 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -65,8 +65,8 @@ meaningful commit messages and: ## Enabling squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form. Users can select or unselect the checkbox at the moment -they are creating the merge request: +on the merge request form. Users can select or clear the check box when they +create the merge request:  diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 56b5774f15b..bded1839f97 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -5,13 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Test Coverage Visualization **(CORE ONLY)** +# Test Coverage Visualization > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. -> - [Feature flag enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) in GitLab 13.4. -> - It's enabled on GitLab.com. -> - It can be disabled per-project. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-feature). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test coverage information of your favorite testing or coverage-analysis tool, and visualize @@ -58,7 +55,9 @@ NOTE: **Note:** The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that the `filename` of a `class` element contains the full path relative to the project root. -## Example test coverage configuration +## Example test coverage configurations + +### JavaScript example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) JavaScript testing and [NYC](https://github.com/istanbuljs/nyc) coverage-tooling to @@ -74,26 +73,84 @@ test: cobertura: coverage/cobertura-coverage.xml ``` -## Enabling the feature +### Java examples + +#### Maven example -This feature comes with the `:coverage_report_view` feature flag enabled by -default. It is enabled on GitLab.com. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance. Test coverage visualization can be enabled or disabled per-project. +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java uses [Maven](https://maven.apache.org/) +to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to +generate the coverage artifact. +You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. -To enable it: +GitLab expects the artifact in the Cobertura format, so you have to execute a few +scripts before uploading it. The `test-jdk11` job tests the code and generates an +XML artifact. The `coverage-jdk-11` job converts the artifact into a Cobertura report: -```ruby -# Instance-wide -Feature.enable(:coverage_report_view) -# or by project -Feature.enable(:coverage_report_view, Project.find(<project id>)) +```yaml +test-jdk11: + stage: test + image: maven:3.6.3-jdk-11 + script: + - 'mvn $MAVEN_CLI_OPTS clean org.jacoco:jacoco-maven-plugin:prepare-agent test jacoco:report' + artifacts: + paths: + - target/site/jacoco/jacoco.xml + +coverage-jdk11: + # Must be in a stage later than test-jdk11's stage. + # The `visualize` stage does not exist by default. + # Please define it first, or chose an existing stage like `deploy`. + stage: visualize + image: haynes/jacoco2cobertura:1.0.3 + script: + # convert report from jacoco to cobertura + - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' + # read the <source></source> tag and prepend the path to every filename attribute + - 'python /opt/source2filename.py target/site/cobertura.xml' + needs: ["test-jdk11"] + dependencies: + - test-jdk11 + artifacts: + reports: + cobertura: target/site/cobertura.xml ``` -To disable it: +#### Gradle example -```ruby -# Instance-wide -Feature.disable(:coverage_report_view) -# or by project -Feature.disable(:coverage_report_view, Project.find(<project id>)) +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java uses [Gradle](https://gradle.org/) +to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to +generate the coverage artifact. +You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. + +GitLab expects the artifact in the Cobertura format, so you have to execute a few +scripts before uploading it. The `test-jdk11` job tests the code and generates an +XML artifact. The `coverage-jdk-11` job converts the artifact into a Cobertura report: + +```yaml +test-jdk11: + stage: test + image: gradle:6.6.1-jdk11 + script: + - 'gradle test jacocoTestReport' # jacoco must be configured to create an xml report + artifacts: + paths: + - build/jacoco/jacoco.xml + +coverage-jdk11: + # Must be in a stage later than test-jdk11's stage. + # The `visualize` stage does not exist by default. + # Please define it first, or chose an existing stage like `deploy`. + stage: visualize + image: haynes/jacoco2cobertura:1.0.3 + script: + # convert report from jacoco to cobertura + - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' + # read the <source></source> tag and prepend the path to every filename attribute + - 'python /opt/source2filename.py build/cobertura.xml' + needs: ["test-jdk11"] + dependencies: + - test-jdk11 + artifacts: + reports: + cobertura: build/cobertura.xml ``` diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index d1833318a85..e7abf6e5fb6 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Draft merge requests +# Draft merge requests **(CORE)** If a merge request is not yet ready to be merged, perhaps due to continued development or open threads, you can prevent it from being accepted before it's ready by flagging @@ -16,10 +16,12 @@ being merged, and it will stay disabled until the "Draft" flag has been removed. ## Adding the "Draft" flag to a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. +> - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a Draft: +- Click the **Mark as draft** button on the top-right corner of the merge request's page. - Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on **Start the title with Draft:**, under the title box, when editing the merge request's description will have the same effect. @@ -28,15 +30,16 @@ There are several ways to flag a merge request as a Draft: - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. -- Add `draft:` or `Draft:` to the start of a commit message targeting the merge request's - source branch. This is not a toggle, and doing it again in another commit will have - no effect. +- Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the + merge request's source branch. This is not a toggle, and doing it again in another + commit will have no effect. ## Removing the "Draft" flag from a merge request Similar to above, when a Merge Request is ready to be merged, you can remove the `Draft` flag in several ways: +- Click the **Mark as ready** button on the top-right corner of the merge request's page. - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge request's description, will have the same effect. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md new file mode 100644 index 00000000000..327a52a05ab --- /dev/null +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -0,0 +1,142 @@ +--- +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 and burnup charts **(STARTER)** + +[Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone. + + + +## Burndown charts + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. + +Burndown charts show the number of issues over the course of a milestone. + + + +At a glance, you see the current state for the completion a given milestone. +Without them, you would have to organize the data from the milestone and plot it +yourself to have the same sense of progress. + +GitLab plots it for you and presents it in a clear and beautiful chart. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, check the video demonstration on [Mapping work versus time with burndown charts](https://www.youtube.com/watch?v=zJU2MuRChzs). + +To view a project's burndown chart: + +1. In a project, navigate to **Issues > Milestones**. +1. Select a milestone from the list. + +To view a group's burndown chart: + +1. In a group, navigate to **Issues > Milestones**. +1. Select a milestone from the list. + +### Use cases for burndown charts + +Burndown charts are generally used for tracking and analyzing the completion of +a milestone. Therefore, their use cases are tied to the +[use you are assigning your milestone to](index.md). + +For example, suppose you lead a team of developers in a large company, +and you follow this workflow: + +- Your company set the goal for the quarter to deliver 10 new features for your app + in the upcoming major release. +- You create a milestone, and remind your team to assign that milestone to every new issue + and merge request that's part of the launch of your app. +- Every week, you open the milestone, visualize the progress, identify the gaps, + and help your team to get their work done. +- Every month, you check in with your supervisor, and show the progress of that milestone + from the burndown chart. +- By the end of the quarter, your team successfully delivered 100% of that milestone, as + it was taken care of closely throughout the whole quarter. + +### How burndown charts work + +A burndown chart is available for every project or group milestone that has been attributed a **start +date** and a **due date**. + +NOTE: **Note:** +You're able to [promote project](index.md#promoting-project-milestones-to-group-milestones) to group milestones and still see the **burndown chart** for them, respecting license limitations. + +The chart indicates the project's progress throughout that milestone (for issues assigned to it). + +In particular, it shows how many issues were or are still open for a given day in the +milestone's corresponding period. + +The burndown chart can also be toggled to display the cumulative open issue +weight for a given day. When using this feature, make sure issue weights have +been properly assigned, since an open issue with no weight adds zero to the +cumulative value. + +### Fixed burndown charts + +For milestones created before GitLab 13.5, burndown charts have an additional toggle to +switch between Legacy and Fixed views. + +| Legacy | Fixed | +| ----- | ----- | +|  |  | + +**Fixed burndown** charts track the full history of milestone activity, from its creation until the +milestone expires. After the milestone due date passes, issues removed from the milestone no longer +affect the chart. + +**Legacy burndown** charts track when issues were created and when they were last closed, not their +full history. For each day, a legacy burndown chart takes the number of open issues and the issues +created that day, and subtracts the number of issues closed that day. +Issues that were created and assigned a milestone before its start date (and remain open as of the +start date) are considered as having been opened on the start date. +Therefore, when the milestone start date is changed, the number of opened issues on each day may +change. +Reopened issues are considered as having been opened on the day after they were last closed. + +## Burnup charts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. + +Burnup charts show the assigned and completed work for a milestone. + + + +To view a project's burnup chart: + +1. In a project, navigate to **Issues > Milestones**. +1. Select a milestone from the list. + +To view a group's burnup chart: + +1. In a group, navigate to **Issues > Milestones**. +1. Select a milestone from the list. + +### How burnup charts work + +Burnup charts have separate lines for total work and completed work. The total line +shows when scope is reduced or added to a milestone. The completed work is a count +of issues closed. + +Burnup charts can show either the total number of issues or total weight for each +day of the milestone. Use the toggle above the charts to switch between total +and weight. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 0c8bba831a9..5aa5534dd37 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,89 +1,5 @@ --- -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 +redirect_to: './burndown_and_burnup_charts.md' --- -# Burndown Charts **(STARTER)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at` -> value, so the burndown chart considers them as closed on the milestone -> `start_date`. In that case, a warning will be displayed. - -## Overview - -Burndown Charts are visual representations of the progress of completing a milestone. - - - -At a glance, you see the current state for the completion a given milestone. -Without them, you would have to organize the data from the milestone and plot it -yourself to have the same sense of progress. - -GitLab Starter plots it for you and presents it in a clear and beautiful chart. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, check the video demonstration on [Mapping work versus time with Burndown Charts](https://www.youtube.com/watch?v=zJU2MuRChzs). - -## Use cases - -Burndown Charts are generally used for tracking and analyzing the completion of -a milestone. Therefore, their use cases are tied to the -[use you are assigning your milestone to](index.md). - -For example, suppose you lead a team of developers in a large company, -and you follow this workflow: - -- Your company set the goal for the quarter to deliver 10 new features for your app - in the upcoming major release. -- You create a milestone, and remind your team to assign that milestone to every new issue - and merge request that's part of the launch of your app. -- Every week, you open the milestone, visualize the progress, identify the gaps, - and help your team to get their work done. -- Every month, you check in with your supervisor, and show the progress of that milestone - from the Burndown Chart. -- By the end of the quarter, your team successfully delivered 100% of that milestone, as - it was taken care of closely throughout the whole quarter. - -## How it works - -A Burndown Chart is available for every project or group milestone that has been attributed a **start -date** and a **due date**. - -Find your project's **Burndown Chart** under **Project > Issues > Milestones**, -and select a milestone from your current ones, while for group's, access the **Groups** dashboard, -select a group, and go through **Issues > Milestones** on the sidebar. - -NOTE: **Note:** -You're able to [promote project](index.md#promoting-project-milestones-to-group-milestones) to group milestones and still see the **Burndown Chart** for them, respecting license limitations. - -The chart indicates the project's progress throughout that milestone (for issues assigned to it). - -In particular, it shows how many issues were or are still open for a given day in the -milestone's corresponding period. - -The Burndown Chart tracks when issues were created and when they were last closed—not their full history. For each day, it takes the number of issues still open and issues created that day and subtracts the number of issues closed that day. -**Issues that were created and assigned a milestone before its start date—and remain open as of the start date—are considered as having been opened on the start date**. Therefore, when the milestone start date is changed the number of opened issues on each day may change. -Reopened issues are -considered as having been opened on the day after they were last closed. - -The Burndown Chart can also be toggled to display the cumulative open issue -weight for a given day. When using this feature, make sure issue weights have -been properly assigned, since an open issue with no weight adds zero to the -cumulative value. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +This document was moved to [another location](./burndown_and_burnup_charts.md). diff --git a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png Binary files differnew file mode 100644 index 00000000000..8d6ba1d4fa7 --- /dev/null +++ b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png diff --git a/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png b/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png Binary files differnew file mode 100644 index 00000000000..a532bfeeca0 --- /dev/null +++ b/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png diff --git a/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png b/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png Binary files differnew file mode 100644 index 00000000000..5824fc59ce5 --- /dev/null +++ b/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png diff --git a/doc/user/project/milestones/img/burndown_chart.png b/doc/user/project/milestones/img/burndown_chart_v13_5.png Binary files differindex e06b24f9907..e06b24f9907 100644 --- a/doc/user/project/milestones/img/burndown_chart.png +++ b/doc/user/project/milestones/img/burndown_chart_v13_5.png diff --git a/doc/user/project/milestones/img/burnup_chart_v13_5.png b/doc/user/project/milestones/img/burnup_chart_v13_5.png Binary files differnew file mode 100644 index 00000000000..a850caba348 --- /dev/null +++ b/doc/user/project/milestones/img/burnup_chart_v13_5.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 9d02a22f91e..8cbed3de1c6 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -7,8 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Milestones -## Overview - Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. @@ -152,7 +150,7 @@ There are also tabs below these that show the following: For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. - + ### Group Burndown Charts **(STARTER)** diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index c3825371030..a7a72ca4d82 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -223,7 +223,7 @@ This is how an example usage can look like: ```yaml test: script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - docker pull $CI_REGISTRY/group/other-project:latest - docker run $CI_REGISTRY/group/other-project:latest ``` @@ -236,5 +236,4 @@ to projects and their project permissions. ### API -GitLab API cannot be used via `CI_JOB_TOKEN` but there is a [proposal](https://gitlab.com/gitlab-org/gitlab/-/issues/35067) -to support it. +GitLab API can be used via `CI_JOB_TOKEN`, see [the relevant documentation](../../api/README.md#gitlab-ci-job-token). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 735d27ec04d..810538ab460 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -30,6 +30,8 @@ to do it for you. To help you out, we've gathered some instructions on how to do that for the most popular hosting services: +<!-- vale gitlab.Spelling = NO --> + - [Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) @@ -41,6 +43,8 @@ for the most popular hosting services: - [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) - [Microsoft](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/bb727018(v=technet.10)) +<!-- vale gitlab.Spelling = YES --> + If your hosting service is not listed above, you can just try to search the web for `how to add dns record on <my hosting service>`. 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 badafa478ef..9b43dd58afe 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 @@ -61,7 +61,6 @@ according to the type of domain you want to use with your Pages site: - [For subdomains](#for-subdomains), `subdomain.example.com`. - [For both](#for-both-root-and-subdomains). -NOTE: **Note:** You can [configure IPv6 on self-managed instances](../../../../administration/pages/index.md#advanced-configuration), but IPv6 is not currently configured for Pages on GitLab.com. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214718) for details. @@ -250,8 +249,8 @@ You can use any certificate satisfying the following requirements: - **A private key**, it's an encrypted key which validates your PEM against your domain. -NOTE: **Note:** -[Cloudflare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), for example, meet these requirements. +For example, [Cloudflare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) +meet these requirements. #### Steps @@ -269,7 +268,6 @@ NOTE: **Note:** just jumping a line between them. 1. Copy your private key and paste it in the last field. -NOTE: **Note:** **Do not** open certificates or encryption keys in regular text editors. Always use code editors (such as Sublime Text, Atom, Dreamweaver, Brackets, etc). @@ -290,8 +288,8 @@ 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). +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 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 4b4b430b663..24b202dfdbd 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 @@ -25,7 +25,7 @@ This feature covers only certificates for **custom domains**, not the wildcard c Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have: -- Created a [project](../getting_started_part_two.md) in GitLab +- Created a [project](../index.md#getting-started) in GitLab containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](index.md) pointing it to your Pages website. @@ -33,7 +33,6 @@ Before you can enable automatic provisioning of an SSL certificate for your doma and verified your ownership. - Verified your website is up and running, accessible through your custom domain. -NOTE: **Note:** GitLab's Let's Encrypt integration is enabled and available on GitLab.com. For **self-managed** GitLab instances, make sure your administrator has [enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). 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 86f36447b93..f19334a1764 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 @@ -2,4 +2,4 @@ redirect_to: 'pages_ci_cd_template.md' --- -This document was moved to [pages_ci_cd_template.md](pages_ci_cd_template.md). +This document was moved to [another location](pages_ci_cd_template.md). diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index de9bd97b262..7dc3d2197b5 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -53,4 +53,4 @@ You can take some **optional** further steps:  - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) - from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the config file. + from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 9272b1f9093..5ef0c4cc7b9 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -11,12 +11,9 @@ according to your intended website's URL. ## GitLab Pages default domain names -NOTE: **Note:** -If you use your own GitLab instance to deploy your -site with GitLab Pages, check with your sysadmin what's your -Pages wildcard domain. This guide is valid for any GitLab instance, -you just need to replace Pages wildcard domain on GitLab.com -(`*.gitlab.io`) with your own. +If you use your own GitLab instance to deploy your site with GitLab Pages, verify your Pages +wildcard domain with your sysadmin. This guide is valid for any GitLab instance, provided that you +replace the Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. If you set up a GitLab Pages project on GitLab, it will automatically be accessible under a diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 9bc9fe97fd3..4bf5300aa13 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1 +1,5 @@ +--- +redirect_to: 'custom_domains_ssl_tls_certification/index.md' +--- + This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 6c3b911d033..4f389716f08 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -124,3 +124,24 @@ If you are running a self-managed instance of GitLab (GitLab Community Edition a [follow the administration steps](../../../administration/pages/index.md) to configure Pages. <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. + +## Security for GitLab Pages + +If your username is `foo`, your GitLab Pages website is located at `foo.gitlab.io`. +GitLab allows usernames to contain a `.`, so a user named `bar.foo` could create +a GitLab Pages website `bar.foo.gitlab.io` that effectively is a subdomain of your +`foo.gitlab.io` website. Be careful if you use JavaScript to set cookies for your website. +The safe way to manually set cookies with JavaScript is to not specify the `domain` at all: + +```javascript +// Safe: This cookie is only visible to foo.gitlab.io +document.cookie = "key=value"; + +// Unsafe: This cookie is visible to foo.gitlab.io and its subdomains, +// regardless of the presence of the leading dot. +document.cookie = "key=value;domain=.foo.gitlab.io"; +document.cookie = "key=value;domain=foo.gitlab.io"; +``` + +This issue doesn't affect users with a custom domain, or users who don't set any +cookies manually with JavaScript. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index cea6bab1a50..b97d5328c07 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -173,7 +173,7 @@ Most modern browsers support downloading files in a compressed format. This speeds up downloads by reducing the size of files. Before serving an uncompressed file, Pages will check whether the same file -exists with a `.gz` extension. If it does, and the browser supports receiving +exists with a `.br` or `.gz` extension. If it does, and the browser supports receiving compressed files, it will serve that version instead of the uncompressed one. To take advantage of this feature, the artifact you upload to the Pages should @@ -182,14 +182,17 @@ have this structure: ```plaintext public/ ├─┬ index.html +│ | index.html.br │ └ index.html.gz │ ├── css/ │ └─┬ main.css +│ | main.css.br │ └ main.css.gz │ └── js/ └─┬ main.js + | main.js.br └ main.js.gz ``` @@ -202,6 +205,7 @@ pages: script: # Build the public/ directory first - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \; + - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec brotli -f -k {} \; ``` By pre-compressing the files and including both versions in the artifact, Pages @@ -255,9 +259,8 @@ instead. Here are some examples of what will happen given the above Pages site: | `/other/index` | `200 OK` | `public/other/index.html` | | `/other/index.html` | `200 OK` | `public/other/index.html` | -NOTE: **Note:** -When `public/data/index.html` exists, it takes priority over the `public/data.html` -file for both the `/data` and `/data/` URL paths. +Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file +for both the `/data` and `/data/` URL paths. ## Frequently Asked Questions 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 708d886b352..02d1dd7898a 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -33,9 +33,8 @@ To follow along with this tutorial, we assume you already have: Once you have the requirements addressed, follow the instructions below to learn how to obtain the certificate. -NOTE: **Note:** -The instructions below were tested on macOS Mojave. For other -operating systems the steps might be slightly different. Follow the +Note that these instructions were tested on macOS Mojave. For other operating systems the steps +might be slightly different. Follow the [CertBot instructions](https://certbot.eff.org/) according to your OS. 1. On your computer, open a terminal and navigate to your repository's diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b6b881b961e..b3705a5835a 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -20,11 +20,9 @@ on your GitLab instance. When enabled, only For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v=tSPAr5mQYc8). 1. Navigate to your project's **Settings > General** and expand **Visibility, project features, permissions**. -1. Toggle the **Pages** button to enable the access control. - NOTE: **Note:** - If you don't see the toggle button, that means that it's not enabled. - Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). +1. Toggle the **Pages** button to enable the access control. If you don't see the toggle button, + that means it isn't enabled. Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). 1. The Pages access control dropdown allows you to set who can view pages hosted with GitLab Pages, depending on your project's visibility: @@ -48,9 +46,10 @@ can access the website. ## Terminating a Pages session -If you want to log out from your Pages website, -you can do so by revoking application access token for GitLab Pages: +To sign out of your GitLab Pages website, revoke the application access token +for GitLab Pages: -1. Navigate to your profile's **Settings > Applications**. -1. Find **Authorized applications** at the bottom of the page. -1. Find **GitLab Pages** and press the **Revoke** button. +1. In the top menu, select your profile, and then select **Settings**. +1. In the left sidebar, select **Applications**. +1. Scroll to the **Authorized applications** section, find the **GitLab Pages** + entry, and select its **Revoke** button. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index ae7b1b4fa6e..60fbf368061 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -6,15 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create redirects for GitLab Pages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4. -> - It's [deployed behind a feature flag](#enable-or-disable-redirects), disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-redirects). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. -In GitLab Pages, you can [enable](#enable-or-disable-redirects) the redirects feature to configure rules to forward one URL to another using HTTP redirects. GitLab Pages uses -[Netlify style redirects](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). +In GitLab Pages, you can configure rules to forward one URL to another using +[Netlify style](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) +HTTP redirects. ## Supported features @@ -22,8 +22,10 @@ GitLab Pages only supports the [`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), and `.toml` files are not supported. -Redirects are only supported at a basic level, and GitLab Pages doesn't support all -[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/): +Redirects are only supported at a basic level. GitLab Pages doesn't support all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/). + +Note that supported paths must start with a forward slash `/`. | Feature | Supported | Example | | ------- | --------- | ------- | @@ -37,12 +39,9 @@ Redirects are only supported at a basic level, and GitLab Pages doesn't support | Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | | Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | -NOTE: **Note:** -Supported paths must start with a forward slash `/`. - ## Create redirects -To create redirects after [enabling](#enable-or-disable-redirects) the feature, +To create redirects, create a configuration file named `_redirects` in the `public/` directory of your GitLab Pages site. @@ -78,8 +77,7 @@ is ignored because `hello.html` exists: /projectname/hello.html /projectname/world.html 302 ``` -NOTE: **Note:** -GitLab does not support Netlify's +GitLab doesn't support Netlify's [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. @@ -105,19 +103,19 @@ rule 10: valid rule 11: valid ``` -## Enable or disable redirects +## Disable redirects -Redirects in GitLab Pages is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +Redirects in GitLab Pages is under development, and is deployed behind a feature flag +that is **enabled by default**. -For [Omnibus installations](../../../administration/pages/index.md), define the +To disable redirects, for [Omnibus installations](../../../administration/pages/index.md), define the `FF_ENABLE_REDIRECTS` environment variable in the [global settings](../../../administration/pages/index.md#global-settings). Add the following line to `/etc/gitlab/gitlab.rb` and [reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). ```ruby -gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'true' +gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'false' ``` For [source installations](../../../administration/pages/source.md), define the @@ -125,6 +123,6 @@ For [source installations](../../../administration/pages/source.md), define the [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): ```shell -export FF_ENABLE_REDIRECTS="true" +export FF_ENABLE_REDIRECTS="false" /path/to/pages/bin/gitlab-pages -config gitlab-pages.conf ``` diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 3d0cb1bf3a5..7265fd330e3 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -48,7 +48,7 @@ that the `master` branch is protected by default. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11. -Since GitLab 8.11, we added another layer of branch protection which provides +In GitLab 8.11 and later, we added another layer of branch protection which provides more granular management of protected branches. The "Developers can push" option was replaced by an "Allowed to push" setting which can be set to allow/prohibit Maintainers and/or Developers to push to a protected branch. @@ -185,6 +185,8 @@ When enabled, all merge requests targeting these branches will require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules. + ## Running pipelines on protected branches The permission to merge or push to protected branches is used to define if a user can diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 518cf472b50..2f1b05f481e 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -39,22 +39,22 @@ The following quick actions are applicable to descriptions, discussions and thre | `/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. | +| `/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>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | | `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | | `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | | `/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. | +| `/lock` | ✓ | ✓ | | Lock the discussions. | | `/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](../../operations/incident_management/status_page.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. | +| `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | +| `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | | `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | | `/remove_due_date` | ✓ | | | Remove due date. | @@ -74,11 +74,12 @@ The following quick actions are applicable to descriptions, discussions and thre | `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/target_branch <local branch name>` | | ✓ | | Set target branch. | | `/title <new title>` | ✓ | ✓ | ✓ | Change title. | -| `/todo` | ✓ | ✓ | ✓ | Add a To-Do. | +| `/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. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | +| `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | +| `/unlock` | ✓ | ✓ | | Unlock the discussions. | | `/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. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 6c8aacd12b3..962d612cac1 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -47,22 +47,20 @@ To view a list of releases: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. -NOTE: **Note:** -Only users with Developer permissions or higher can create releases. -Read more about [Release permissions](../../../user/permissions.md#project-members-permissions). - You can create a release in the user interface, or by using the [Releases API](../../../api/releases/index.md#create-a-release). We recommend using the API to create releases as one of the last steps in your CI/CD pipeline. +Only users with Developer permissions or higher can create releases. +Read more about [Release permissions](../../../user/permissions.md#project-members-permissions). + To create a new release through the GitLab UI: 1. Navigate to **Project overview > Releases** and click the **New release** button. 1. In the [**Tag name**](#tag-name) box, enter a name. - NOTE: **Note:** Creating a release based on an existing tag using the user interface is not yet supported. However, this is possible using the [Releases API](../../../api/releases/index.md#create-a-release). @@ -88,7 +86,6 @@ release tag. When the `released_at` date and time has passed, the badge is autom > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26016) in GitLab 12.6. Asset link editing was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9427) in GitLab 12.10. -NOTE: **Note:** Only users with Developer permissions or higher can edit releases. Read more about [Release permissions](../../../user/permissions.md#project-members-permissions). @@ -225,7 +222,6 @@ The release title can be customized using the **Release title** field when creating or editing a release. If no title is provided, the release's tag name is used instead. -NOTE: **Note:** Guest users of private projects are allowed to view the **Releases** page but are _not_ allowed to view details about the Git repository (in particular, tag names). Because of this, release titles are replaced with a generic @@ -254,7 +250,6 @@ Every release has a description. You can add any text you like, but we recommend including a changelog to describe the content of your release. This helps users quickly scan the differences between each release you publish. -NOTE: **Note:** [Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and Release note descriptions are unrelated. Description supports [Markdown](../../markdown.md). @@ -334,8 +329,7 @@ generate release evidence for an existing release. Because of this, each release can have multiple release evidence snapshots. You can view the release evidence and its details on the Releases page. -NOTE: **Note:** -When the issue tracker is disabled, release evidence [cannot be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). +When the issue tracker is disabled, release evidence [can't be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). Here is an example of a release evidence object: @@ -431,10 +425,13 @@ ruby: junit: rspec.xml ``` -If the pipeline ran successfully, when you create your release, the `rspec.xml` file is saved as release evidence. +If the pipeline ran successfully, when you create your release, the `rspec.xml` file is saved as +release evidence. -NOTE: **Note:** -If you [schedule release evidence collection](#schedule-release-evidence-collection), some artifacts may already be expired by the time of evidence collection. To avoid this you can use the [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). +If you [schedule release evidence collection](#schedule-release-evidence-collection), +some artifacts may already be expired by the time of evidence collection. To avoid this you can use +the [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) +keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). ### Schedule release evidence collection @@ -449,21 +446,6 @@ In the API: - If you do not specify a `released_at` date, release evidence is collected on the date the release is created. -### Disable release evidence display **(CORE ONLY)** - -The `:release_evidence_collection` feature flag is enabled by default in GitLab -self-managed instances. To turn it off, ask a GitLab administrator with Rails console -access to run the following command: - -```ruby -Feature.disable(:release_evidence_collection) -``` - -NOTE: **Note:** -Release evidence is collected regardless of this feature flag, -which only enables or disables the display of the data on the -Releases page. - ## GitLab Releaser > [Introduced](https://gitlab.com/gitlab-org/gitlab-releaser/-/merge_requests/6) in GitLab 12.10. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index e90f0a7354c..b0aa7569579 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -14,7 +14,7 @@ can create a fork. A fork is a personal copy of the repository and all its branches, which you create in a namespace of your choice. This way you can make changes in your own fork and -submit them through a merge request to the repo you don't have access to. +submit them through a merge request to the repository you don't have access to. ## Creating a fork diff --git a/doc/user/project/repository/img/repository_mirroring_push_settings.png b/doc/user/project/repository/img/repository_mirroring_push_settings.png Binary files differindex d055cc580c4..9fc25dd3b25 100644 --- a/doc/user/project/repository/img/repository_mirroring_push_settings.png +++ b/doc/user/project/repository/img/repository_mirroring_push_settings.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 536cae263b8..5473439a162 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -86,7 +86,7 @@ according to the markup language. | [reStructuredText](https://docutils.sourceforge.io/rst.html) | `rst` | | [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` | | [Textile](https://textile-lang.com/) | `textile` | -| [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | +| [Rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | | [Org mode](https://orgmode.org/) | `org` | | [creole](http://www.wikicreole.org/) | `creole` | | [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | @@ -234,7 +234,7 @@ lock your files to prevent any conflicting changes. ## Repository's API -You can access your repos via [repository API](../../../api/repositories.md). +You can access your repositories via [repository API](../../../api/repositories.md). ## Clone in Apple Xcode 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 28fdda07b05..ad79fd8a8f9 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 @@ -19,7 +19,7 @@ over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and [BFG](https://rtyley.github.io/bfg-repo-cleaner/). DANGER: **Danger:** -Rewriting repository history is a destructive operation. Make sure to backup your repository before +Rewriting repository history is a destructive operation. Make sure to back up 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). @@ -230,6 +230,7 @@ This will: - Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily cause the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. +- Unlink any unused LFS objects currently attached to your project, freeing up storage space. - Recalculate the size of your repository on disk. You will receive an email notification with the recalculated repository size after the cleanup has completed. @@ -266,21 +267,20 @@ You can still: - Create new issues. - Clone the project. -If you exceed the repository size limit, you might try to: +If you exceed the repository size limit, you can: 1. Remove some data. 1. Make a new commit. 1. Push back to the repository. -Perhaps you might also: +If these actions are insufficient, you can 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 +Unfortunately, this workflow doesn't work. Deleting files in a commit doesn't actually reduce the +size of the repository, because the earlier commits and blobs still exist. Instead, you must rewrite +history. We recommend the open-source community-maintained tool [`git filter-repo`](https://github.com/newren/git-filter-repo). NOTE: **Note:** diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index e1d2c20850b..188699e0c77 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -56,6 +56,7 @@ The following are some possible use cases for repository mirroring: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249) in GitLab Enterprise Edition 8.7. > - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. +> - [LFS support over HTTPS added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in 13.5 For an existing project, you can set up push mirroring as follows: @@ -181,7 +182,7 @@ To set up a mirror from GitLab to AWS CodeCommit: not confuse it with the IAM user ID or AWS keys of this user. 1. Copy or download special Git HTTPS user ID and password. -1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repo. +1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. 1. Open your new repository and click **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). 1. In GitLab, open the repository to be push-mirrored. 1. Click **Settings > Repository** and expand **Mirroring repositories**. @@ -192,7 +193,7 @@ To set up a mirror from GitLab to AWS CodeCommit: ``` Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** from the IAM Git - credentials created earlier. Replace `<your_codecommit_repo>` with the name of your repo in CodeCommit. + credentials created earlier. Replace `<your_codecommit_repo>` with the name of your repository in CodeCommit. 1. For **Mirror direction**, select **Push**. 1. For **Authentication method**, select **Password** and fill in the **Password** field with the special IAM Git clone user ID **password** created earlier in AWS. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 972a46ee7a3..9b420d84f50 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -26,7 +26,7 @@ For a commit or tag to be *verified* by GitLab: [Omnibus install custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). - The signing time has to be within the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5) which is usually up to three years. -- The signing time is equal or later then commit time. +- The signing time is equal or later than commit time. NOTE: **Note:** Certificate revocation lists are checked on a daily basis via background worker. diff --git a/doc/user/project/requirements/img/requirement_create_v13_5.png b/doc/user/project/requirements/img/requirement_create_v13_5.png Binary files differnew file mode 100644 index 00000000000..ef1bab6e6d2 --- /dev/null +++ b/doc/user/project/requirements/img/requirement_create_v13_5.png diff --git a/doc/user/project/requirements/img/requirement_view_v13_5.png b/doc/user/project/requirements/img/requirement_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..7fcb24a5e3b --- /dev/null +++ b/doc/user/project/requirements/img/requirement_view_v13_5.png diff --git a/doc/user/project/requirements/img/requirements_list_v13_1.png b/doc/user/project/requirements/img/requirements_list_v13_1.png Binary files differdeleted file mode 100644 index 0ebda571928..00000000000 --- a/doc/user/project/requirements/img/requirements_list_v13_1.png +++ /dev/null diff --git a/doc/user/project/requirements/img/requirements_list_v13_5.png b/doc/user/project/requirements/img/requirements_list_v13_5.png Binary files differnew file mode 100644 index 00000000000..19516e5e66e --- /dev/null +++ b/doc/user/project/requirements/img/requirements_list_v13_5.png diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 9d7d3914905..f533f8807d2 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Requirements Management **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. 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. @@ -22,7 +23,7 @@ When a feature is no longer necessary, you can [archive the related requirement] <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). - + ## Create a requirement @@ -32,29 +33,43 @@ can create a new requirement. To create a requirement: 1. From your project page, go to **{requirements}** **Requirements**. -1. Click **New requirement**. -1. Enter a descriptive title and click **Create requirement**. +1. Select **New requirement**. +1. Enter a title and description and select **Create requirement**. -You will see the newly created requirement on the top of the list, as the requirements -list is sorted by creation date in descending order. + + +You can see the newly created requirement on the top of the list, with the requirements +list being sorted by creation date, in descending order. + +## View a requirement + +You can view a requirement from the list by selecting it. + + + +To edit a requirement while viewing it, select the **Edit** icon (**{pencil}**) +next to the requirement title. ## Edit a requirement +> The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. + You can edit a requirement (if you have the necessary privileges) from the requirements list page. To edit a requirement: -1. From the requirements list, click **Edit** (**{pencil}**). -1. Update the title in text input field. -1. Click **Save changes**. +1. From the requirements list, select the **Edit** icon (**{pencil}**). +1. Update the title and description in text input field. You can also mark a + requirement as satisfied in the edit form by using the check box **Satisfied**. +1. Select **Save changes**. ## Archive a requirement You can archive an open requirement (if you have the necessary privileges) while you're in the **Open** tab. -To archive a requirement, click **Archive** (**{archive}**). +To archive a requirement, select **Archive** (**{archive}**). As soon as a requirement is archived, it no longer appears in the **Open** tab. @@ -64,7 +79,7 @@ You can view the list of archived requirements in the **Archived** tab.  -To reopen an archived requirement, click **Reopen**. +To reopen an archived requirement, select **Reopen**. As soon as a requirement is reopened, it no longer appears in the **Archived** tab. @@ -80,7 +95,7 @@ You can search for a requirement from the requirements list page based on the fo To search for a requirement: 1. In a project, go to **{requirements}** **Requirements > List**. -1. Click the **Search or filter results** field. A dropdown menu appears. +1. Select the **Search or filter results** field. A dropdown menu appears. 1. Select the requirement author from the dropdown or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -97,7 +112,7 @@ You can also sort the requirements list by: GitLab supports [requirements test reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing -requirements as Satisfied. +requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)). ### Add the manual job to CI diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index e9b07f54b91..0a1b81a6359 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -10,8 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. -## Overview - Service Desk is a module that allows your team to connect directly with any external party through email right inside of GitLab; no external tools required. An ongoing conversation right where your software is built ensures that user feedback ends @@ -129,7 +127,7 @@ in the email, `%{ISSUE_PATH}` placeholder which will be replaced by 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 +### Using custom email address **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 395d4bf30c5..8fdcf58b5aa 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -8,7 +8,7 @@ type: reference, index, howto # Project settings NOTE: **Note:** -Only project Maintainers and Admin users have the [permissions](../../permissions.md#project-members-permissions) +Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to access a project settings. You can adjust your [project](../index.md) settings by navigating @@ -145,7 +145,7 @@ Here you can run housekeeping, archive, rename, transfer, [remove a fork relatio Archiving a project makes it read-only for all users and indicates that it's no longer actively maintained. Projects that have been archived can also be -unarchived. Only project Owners and Admin users have the +unarchived. Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to archive a project. When a project is archived, the repository, packages, issues, merge requests, and all @@ -162,12 +162,12 @@ To archive a project: #### Unarchiving a project Unarchiving a project removes the read-only restriction on a project, and makes it -available in project listings. Only project Owners and Admin users have the +available in project listings. Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to unarchive a project. To find an archived project: -1. Sign in to GitLab as a user with project Owner or Admin permissions. +1. Sign in to GitLab as a user with project owner or administrator permissions. 1. If you: - Have the project's URL, open the project's page in your browser. - Don't have the project's URL: @@ -186,7 +186,7 @@ Next, to unarchive the project: #### Renaming a repository NOTE: **Note:** -Only project Maintainers and Admin users have the [permissions](../../permissions.md#project-members-permissions) to rename a +Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to rename a repository. Not to be confused with a project's name where it can also be changed from the [general project settings](#general-project-settings). @@ -207,7 +207,7 @@ old URL won't be able to push or pull. Read more about what happens with the #### Transferring an existing project into another namespace NOTE: **Note:** -Only project Owners and Admin users have the [permissions](../../permissions.md#project-members-permissions) +Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: @@ -229,13 +229,13 @@ read what happens with the [redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths). NOTE: **Note:** -GitLab administrators can use the admin interface to move any project to any +GitLab administrators can use the administration interface to move any project to any namespace if needed. #### Delete a project NOTE: **Note:** -Only project owners and admins have [permissions](../../permissions.md#project-members-permissions) to delete a project. +Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. To delete a project: @@ -247,7 +247,7 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group admins can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group +group administrators can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after number of days specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). @@ -270,7 +270,7 @@ To restore a project marked for deletion: Forking is a great way to [contribute to a project](../repository/forking_workflow.md) of which you're not a member. If you want to use the fork for yourself and don't need to send -[merge requests](../merge_requests.md) to the upstream project, +[merge requests](../merge_requests/index.md) to the upstream project, you can safely remove the fork relationship. CAUTION: **Caution:** diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 57cb610a2e9..b6ce21ebea6 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,21 +1,22 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Access 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, howto --- -# Project access tokens **(CORE ONLY)** +# Project access tokens + +NOTE: **Note:** +Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. > - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. -> - It's disabled on GitLab.com. -> - It can be enabled or disabled by project. +> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can [disable 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). You can also use project access tokens with Git to authenticate over HTTP or SSH. +Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP. Project access tokens expire on the date you define, at midnight UTC. @@ -48,12 +49,12 @@ API calls made with a project access token are associated with the corresponding 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 -records will be moved to a system-wide user with the username "Ghost User". For more information, -see [Associated Records](../../profile/account/delete_account.md#associated-records). +- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. +- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. + +When the project access token is [revoked](#revoking-a-project-access-token) the bot user is then deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). -Project bot users are a [GitLab-created service account](../../../subscriptions/self_managed/index.md#choose-the-number-of-users), but count as a licensed seat. -These users will not count against your licensed seat in the future when [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) is resolved. +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#choose-the-number-of-users) and do not count as licensed seats. ## Revoking a project access token @@ -74,33 +75,3 @@ 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 are deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance, globally or by project. - -To disable it globally: - -```ruby -Feature.disable(:resource_access_token) -``` - -To disable it for a specific project: - -```ruby -Feature.disable(:resource_access_token, project) -``` - -To enable it globally: - -```ruby -Feature.enable(:resource_access_token) -``` - -To enable it for a specific project: - -```ruby -Feature.enable(:resource_access_token, project) -``` diff --git a/doc/user/project/static_site_editor/img/front_matter_ui_v13_4.png b/doc/user/project/static_site_editor/img/front_matter_ui_v13_4.png Binary files differnew file mode 100644 index 00000000000..89864858ed3 --- /dev/null +++ b/doc/user/project/static_site_editor/img/front_matter_ui_v13_4.png diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index ce14cefba92..8a2f62ec7a2 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -6,50 +6,43 @@ type: reference, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- -# Static Site Editor +# Static Site Editor **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. -> - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1. -> - Markdown front matter hidden on the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216834) in GitLab 13.1. -> - Support for `*.md.erb` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223171) in GitLab 13.2. > - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. -DANGER: **Danger:** -In GitLab 13.0, we [introduced breaking changes](https://gitlab.com/gitlab-org/gitlab/-/issues/213282) -to the URL structure of the Static Site Editor. Follow the instructions in this -[snippet](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/snippets/1976539) -to update your project with the latest changes. - -Static Site Editor enables users to edit content on static websites without +Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or Git commands. A contributor to your project can quickly edit a Markdown page and submit the changes for review. ## Use cases -The Static Site Editors allows collaborators to submit changes to static site +The Static Site Editor allows collaborators to submit changes to static site files seamlessly. For example: -- Non-technical collaborators can easily edit a page directly from the browser; they don't need to know Git and the details of your project to be able to contribute. +- Non-technical collaborators can easily edit a page directly from the browser; + they don't need to know Git and the details of your project to be able to contribute. - Recently hired team members can quickly edit content. -- Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. +- Temporary collaborators can jump from project to project and quickly edit pages instead + of having to clone or fork every single project they need to submit changes to. ## Requirements - In order use the Static Site Editor feature, your project needs to be -pre-configured with the [Static Site Editor Middleman template](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman). -- The editor needs to be logged into GitLab and needs to be a member of the -project (with Developer or higher permission levels). + pre-configured with the [Static Site Editor Middleman template](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman). +- You need to be logged into GitLab and be a member of the + project (with Developer or higher permission levels). ## How it works -The Static Site Editor is in an early stage of development and only works for +The Static Site Editor is in an early stage of development and only supports Middleman sites for now. You have to use a specific site template to start using it. The project template is configured to deploy a [Middleman](https://middlemanapp.com/) static website with [GitLab Pages](../pages/index.md). -Once your website is up and running, you'll see a button **Edit this page** on +Once your website is up and running, an **Edit this page** button displays on the bottom-left corner of its pages:  @@ -65,44 +58,128 @@ creates a new branch, commits their changes, and opens a merge request. The editor lands directly on the merge request, and then they can assign it to a colleague for review. -## Getting started +## Set up your project First, set up the project. Once done, you can use the Static Site Editor to -easily edit your content. - -### Set up your project - -1. To get started, create a new project from the -[Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) -template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) -or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates). -1. Edit the `data/config.yml` file adding your project's path. -1. Editing the file triggers a CI/CD pipeline to deploy your project with GitLab Pages. +easily [edit your content](#edit-content). + +1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) + template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) + or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates). +1. Edit the [`data/config.yml`](#configuration-files) configuration file + to replace `<username>` and `<project-name>` with the proper values for + your project's path. This triggers a CI/CD pipeline to deploy your project + with GitLab Pages. 1. When the pipeline finishes, from your project's left-side menu, go to **Settings > Pages** to find the URL of your new website. 1. Visit your website and look at the bottom-left corner of the screen to see the new **Edit this page** button. -Anyone satisfying the [requirements](#requirements) will be able to edit the +Anyone satisfying the [requirements](#requirements) can edit the content of the pages without prior knowledge of Git or of your site's codebase. -NOTE: **Note:** -From GitLab 13.1 onwards, the YAML front matter of Markdown files is hidden on the -WYSIWYG editor to avoid unintended changes. To edit it, use the Markdown editing mode, the regular -GitLab file editor, or the Web IDE. +## Edit content + +> - Support for modifying the default merge request title and description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216861) in GitLab 13.5. + +After setting up your project, you can start editing content directly from the Static Site Editor. + +To edit a file: + +1. Visit the page you want to edit. +1. Click the **Edit this page** button. +1. The file is opened in the Static Site Editor in **WYSIWYG** mode. If you + wish to edit the raw Markdown instead, you can toggle the **Markdown** mode + in the bottom-right corner. +1. When you're done, click **Submit changes...**. +1. (Optional) Adjust the default title and description of the merge request that will be submitted with your changes. +1. Click **Submit changes**. +1. A new merge request is automatically created and you can assign a colleague for review. + +### Text + +> Support for `*.md.erb` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223171) in GitLab 13.2. + +The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing text. + +### Images + +> - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1. + +You can add image files on the WYSIWYG mode by clicking the image icon (**{doc-image}**). +From there, link to a URL, add optional [ALT text](https://moz.com/learn/seo/alt-text), +and you're done. The link can reference images already hosted in your project, an asset hosted +externally on a content delivery network, or any other external URL. The editor renders thumbnail previews +so you can verify the correct image is included and there aren't any references to missing images. +default directory (`source/images/`). + +### Videos -### Use the Static Site Editor to edit your content +> - Support for embedding YouTube videos through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216642) in GitLab 13.5. -For instance, suppose you are a recently hired technical writer at a large -company and a new feature has been added to the company product. +You can embed YouTube videos on the WYSIWYG mode by clicking the video icon (**{live-preview}**). +The following URL/ID formats are supported: -1. You are assigned the task of updating the documentation. -1. You visit a page and see content that needs to be edited. -1. Click the **Edit this page** button on the production site. -1. The file is opened in the Static Site Editor in **WYSIWYG** mode. If you wish to edit the raw Markdown - instead, you can toggle the **Markdown** mode in the bottom-right corner. -1. You edit the file right there and click **Submit changes**. -1. A new merge request is automatically created and you assign it to your colleague for review. +- YouTube watch URL (e.g. `https://www.youtube.com/watch?v=0t1DgySidms`) +- YouTube embed URL (e.g. `https://www.youtube.com/embed/0t1DgySidms`) +- YouTube video ID (e.g. `0t1DgySidms`) + +### Front matter + +> - Markdown front matter hidden on the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216834) in GitLab 13.1. +> - Ability to edit page front matter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235921) in GitLab 13.5. + +Front matter is a flexible and convenient way to define page-specific variables in data files +intended to be parsed by a static site generator. It is commonly used for setting a page's +title, layout template, or author, but can be used to pass any kind of metadata to the +generator as the page renders out to HTML. Included at the very top of each data file, the +front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. + +To edit the front matter from the Static Site Editor you can use the GitLab's regular file editor, +the Web IDE, or easily update the data directly from the WYSIWYG editor: + +1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you + have on the page's front matter. The form is populated with the current data: + +  + +1. Update the values as you wish and close the panel. +1. When you're done, click **Submit changes...**. +1. Describe your changes (add a commit message). +1. Click **Submit changes**. +1. Click **View merge request** and GitLab will take you there. + +Note that support for adding new attributes to the page's front matter from the form is not supported +yet. You can do so by editing the file locally, through the GitLab regular file editor, or through the Web IDE. Once added, the form will load the new fields. + +## Configuration files + +The Static Site Editor uses Middleman's configuration file, `data/config.yml` +to customize the behavior of the project itself and to control the **Edit this +page** button, rendered through the file [`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). + +To [configure the project template to your own project](#set-up-your-project), +you must replace the `<username>` and `<project-name>` in the `data/config.yml` +file with the proper values for your project's path. + +[Other Static Site Generators](#using-other-static-site-generators) used with +the Static Site Editor may use different configuration files or approaches. + +## Using Other Static Site Generators + +Although Middleman is the only Static Site Generator currently officially supported +by the Static Site Editor, you can configure your project's build and deployment +to use a different Static Site Generator. In this case, use the Middleman layout +as an example, and follow a similar approach to properly render an **Edit this page** +button in your Static Site Generator's layout. + +## Upgrade from GitLab 12.10 to 13.0 + +In GitLab 13.0, we [introduced breaking changes](https://gitlab.com/gitlab-org/gitlab/-/issues/213282) +to the URL structure of the Static Site Editor. Follow the instructions in this +[snippet](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/snippets/1976539) +to update your project with the 13.0 changes. ## Limitations -- The Static Site Editor still cannot be quickly added to existing Middleman sites. Follow this [epic](https://gitlab.com/groups/gitlab-org/-/epics/2784) for updates. +- The Static Site Editor still cannot be quickly added to existing Middleman sites. + Follow this [epic](https://gitlab.com/groups/gitlab-org/-/epics/2784) for updates. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 821b42af049..4da9b5f88ff 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -32,7 +32,7 @@ file path fragments to start seeing results. ## Syntax highlighting As expected from an IDE, syntax highlighting for many languages within -the Web IDE will make your direct editing even easier. +the Web IDE makes your direct editing even easier. The Web IDE currently provides: @@ -79,7 +79,7 @@ which apply to the entire Web IDE screen. > - Support for validation based on custom schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. The Web IDE provides validation support for certain JSON and YAML files using schemas -based on the [JSON Schema Store](https://www.schemastore.org/json/). +based on the [JSON Schema Store](https://www.schemastore.org/json/). ### Predefined schemas @@ -143,7 +143,7 @@ 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. +that match the file's path, these settings are enforced on the opened file. The Web IDE currently supports the following `.editorconfig` settings: @@ -166,7 +166,7 @@ review the list of changed files. Once you have finalized your changes, you can add a commit message, commit the changes and directly create a merge request. In case you don't have write -access to the selected branch, you will see a warning, but still be able to create +access to the selected branch, you see a warning, but can still create a new branch and start a merge request. To discard a change in a particular file, click the **Discard changes** button on that @@ -201,8 +201,7 @@ left. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. To switch between your authored and assigned merge requests, click the -dropdown in the top of the sidebar to open a list of merge requests. You will -need to commit or discard all your changes before switching to a different merge +dropdown in the top of the sidebar to open a list of merge requests. You need to commit or discard all your changes before switching to a different merge request. ## Switching branches @@ -211,7 +210,7 @@ request. To switch between branches of the current project repository, click the dropdown 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 +You need to commit or discard all your changes before switching to a different branch. ## Markdown editing @@ -226,7 +225,7 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g 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. +added to the filename. ## Live Preview @@ -249,7 +248,7 @@ The Live Preview feature needs to be enabled in the GitLab instances admin settings. Live Preview is enabled for all projects on GitLab.com - + Once you have done that, you can preview projects with a `package.json` file and a `main` entry point inside the Web IDE. An example `package.json` is shown @@ -292,7 +291,7 @@ to work: [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE ONLY)** If you have the terminal open and the job has finished with its tasks, the -terminal will block the job from finishing for the duration configured in +terminal blocks the job from finishing for the duration configured in [`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window. @@ -308,15 +307,15 @@ In order to enable the Web IDE terminals you need to create the file file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) syntax but with some restrictions: -- No global blocks can be defined (ie: `before_script` or `after_script`) +- No global blocks can be defined (i.e., `before_script` or `after_script`) - Only one job named `terminal` can be added to this file. - Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and `variables` are allowed to be used to configure the job. - To connect to the interactive terminal, the `terminal` job must be still alive - and running, otherwise the terminal won't be able to connect to the job's session. + and running, otherwise the terminal cannot connect to the job's session. By default the `script` keyword has the value `sleep 60` to prevent the job from ending and giving the Web IDE enough time to connect. This means - that, if you override the default `script` value, you'll have to add a command + that, if you override the default `script` value, you have to add a command which would keep the job running, like `sleep`. In the code below there is an example of this configuration file: @@ -333,40 +332,39 @@ terminal: NODE_ENV: "test" ``` -Once the terminal has started, the console will be displayed and we could access +Once the terminal has started, the console is displayed and we could access the project repository files. **Important**. The terminal job is branch dependent. This means that the -configuration file used to trigger and configure the terminal will be the one in +configuration file used to trigger and configure the terminal is the one in the selected branch of the Web IDE. -If there is no configuration file in a branch, an error message will be shown. +If there is no configuration file in a branch, an error message is shown. ### Running interactive terminals in the Web IDE -If Interactive Terminals are available for the current user, the **Terminal** button -will be visible in the right sidebar of the Web IDE. Click this button to open +If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Click this button to open or close the terminal tab. -Once open, the tab will show the **Start Web Terminal** button. This button may +Once open, the tab shows the **Start Web Terminal** button. This button may be disabled if the environment is not configured correctly. If so, a status -message will describe the issue. Here are some reasons why **Start Web Terminal** +message describes the issue. Here are some reasons why **Start Web Terminal** may be disabled: - `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly. - No active private runners are available for the project. -If active, clicking the **Start Web Terminal** button will load the terminal view +If active, clicking the **Start Web Terminal** button loads the terminal view and start connecting to the runner's terminal. At any time, the **Terminal** tab -can be closed and reopened and the state of the terminal will not be affected. +can be closed and reopened and the state of the terminal is not affected. When the terminal is started and is successfully connected to the runner, then the -runner's shell prompt will appear in the terminal. From here, you can enter -commands that will be executed within the runner's environment. This is similar +runner's shell prompt appears in the terminal. From here, you can enter +commands executed within the runner's environment. This is similar to running commands in a local terminal or through SSH. While the terminal is running, it can be stopped by clicking **Stop Terminal**. -This will disconnect the terminal and stop the runner's terminal job. From here, +This disconnects the terminal and stops the runner's terminal job. From here, click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal @@ -408,14 +406,14 @@ terminal: more information. - `$CI_PROJECT_DIR` is a [predefined environment variable](../../../ci/variables/predefined_variables.md) - for GitLab Runner. This is where your project's repository will be. + for GitLab Runners. This is where your project's repository resides. Once you have configured the web terminal for file syncing, then when the web -terminal is started, a **Terminal** status will be visible in the status bar. +terminal is started, a **Terminal** status is visible in the status bar.  -Changes made to your files via the Web IDE will sync to the running terminal +Changes made to your files via the Web IDE sync to the running terminal when: - <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac) @@ -425,9 +423,12 @@ when: ### Limitations -Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming -releases. In the meantime, please note that the user is limited to having only one -active terminal at a time. +The Web IDE has a few limitations: + +- Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, please note that the user is limited to having only one + active terminal at a time. + +- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository will be overwritten with the modified LFS file content. ### Troubleshooting diff --git a/doc/user/project/wiki/img/wiki_sidebar.png b/doc/user/project/wiki/img/wiki_sidebar.png Binary files differdeleted file mode 100644 index ff39c861a73..00000000000 --- a/doc/user/project/wiki/img/wiki_sidebar.png +++ /dev/null diff --git a/doc/user/project/wiki/img/wiki_sidebar_v13_5.png b/doc/user/project/wiki/img/wiki_sidebar_v13_5.png Binary files differnew file mode 100644 index 00000000000..0f445d61d71 --- /dev/null +++ b/doc/user/project/wiki/img/wiki_sidebar_v13_5.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 40ef5e216fd..64608b9a915 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Wiki +# Wiki **(CORE)** A separate system for documentation called Wiki, is built right into each GitLab project. It is enabled by default on all new projects and you can find @@ -19,6 +19,9 @@ You can create Wiki pages in the web interface or [locally using Git](#adding-and-editing-wiki-pages-locally) since every Wiki is a separate Git repository. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, +**group wikis** became available. Their usage is similar to project wikis, with a few [limitations](../../group/index.md#group-wikis). + ## First time creating the Home page The first time you visit a Wiki, you will be directed to create the Home page. @@ -127,10 +130,12 @@ be preceded by the slash (`/`) character. ## Viewing a list of all created wiki pages +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17673/) in GitLab 13.5, wiki pages are displayed as a nested tree in the sidebar and pages overview. + Every wiki has a sidebar from which a short list of the created pages can be found. The list is ordered alphabetically. - + If you have many pages, not all will be listed in the sidebar. Click on **View All Pages** to see all of them. @@ -163,48 +168,13 @@ Similar to versioned diff file views, you can see the changes made in a given Wi > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** > - Git events were [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** -> - It's enabled on GitLab.com. -> - Git access activity creation is managed by a feature flag. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-wiki-events-in-git). **(CORE ONLY)** +> - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** Wiki events (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), and [project](../index.md#project-activity) activity pages. -### Enable or disable Wiki events in Git **(CORE ONLY)** - -Tracking wiki events through Git 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(:wiki_events_on_git_push) -``` - -To enable for just a particular project: - -```ruby -project = Project.find_by_full_path('your-group/your-project') -Feature.enable(:wiki_events_on_git_push, project) -``` - -To disable it: - -```ruby -Feature.disable(:wiki_events_on_git_push) -``` - -To disable for just a particular project: - -```ruby -project = Project.find_by_full_path('your-group/your-project') -Feature.disable(:wiki_events_on_git_push, project) -``` - ## Adding and editing wiki pages locally Since wikis are based on Git repositories, you can clone them locally and edit |
