diff options
Diffstat (limited to 'doc/user/project')
116 files changed, 1801 insertions, 643 deletions
diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 7fa8ec6c5f3..712f8ea0adc 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Adding EKS clusters GitLab supports adding new and existing EKS clusters. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 1195421f8fb..4094828323a 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Adding GKE clusters GitLab supports adding new and existing GKE clusters. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index dce273ce602..fddc9873f17 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Adding and removing Kubernetes clusters GitLab offers integrated cluster creation for the following Kubernetes providers: diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 74a58b93442..1298a24fcac 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Kubernetes clusters > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/35954) in GitLab 10.1 for projects. @@ -30,10 +36,28 @@ Using the GitLab project Kubernetes integration, you can: - View [Logs](#logs). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). +### Supported cluster versions + +GitLab is committed to support at least two production-ready Kubernetes minor versions at any given time. We regularly review the versions we support, and provide a four-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of: + +- Our own needs. +- The versions supported by major managed Kubernetes providers. +- The versions [supported by the Kubernetes community](https://kubernetes.io/docs/setup/release/version-skew-policy/#supported-versions). + +Currently, GitLab supports the following Kubernetes versions: + +- 1.15 +- 1.14 +- 1.13 (deprecated, support ends on November 22, 2020) +- 1.12 (deprecated, support ends on September 22, 2020) + +NOTE: **Note:** +Some GitLab features may support versions outside the range provided here. + ### Deploy Boards **(PREMIUM)** GitLab's Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments.md) running on Kubernetes, +status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -78,8 +102,8 @@ Kubernetes clusters can be used without Auto DevOps. > Introduced in GitLab 8.15. -When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments.md#web-terminals) -support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in +When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) +support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new shell session within your existing containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any deployments, replica sets, and @@ -181,8 +205,8 @@ you can either: ### Setting the environment scope **(PREMIUM)** When adding more than one Kubernetes cluster to your project, you need to differentiate -them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables) work. +them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, will use that cluster. Each scope can only be used by a single @@ -262,7 +286,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use GitLab's cluster integration you can still deploy to your cluster. However, you will need configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#creating-a-custom-environment-variable) + using [environment variables](../../../ci/variables/README.md#custom-environment-variables) before you can interact with the cluster from your jobs. ### Deployment variables @@ -297,7 +321,7 @@ 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.md#configuring-kubernetes-deployments) +[`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 @@ -314,7 +338,7 @@ the deployment job: However, sometimes GitLab can not create them. In such instances, your job will fail with the message: -```text +```plaintext This job failed because the necessary resources were not successfully created. ``` @@ -325,7 +349,7 @@ Reasons for failure include: - The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching - [`environment:name`](../../../ci/environments.md#defining-environments). If your job has no + [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no `environment:name` set, it will not be passed the Kubernetes credentials. NOTE: **NOTE:** diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 5543187b6de..8577231b69b 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,24 +1,36 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Kubernetes Logs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). -By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. +By displaying the logs directly in GitLab in the **Log Explorer**, developers can avoid +managing console tools or jumping to a different interface. NOTE: **Kubernetes + GitLab** -Everything you need to build, test, deploy, and run your app at scale. +Everything you need to build, test, deploy, and run your application at scale. [Learn more](https://about.gitlab.com/solutions/kubernetes/). ## Overview -[Kubernetes](https://kubernetes.io) logs can be viewed directly within GitLab. +[Kubernetes](https://kubernetes.io) logs can be viewed directly within GitLab with +the **Log Explorer**.  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +To learn more, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). + ## Requirements -[Deploying to a Kubernetes environment](../deploy_boards.md#enabling-deploy-boards) is required in order to be able to use Logs. +[Deploying to a Kubernetes environment](../deploy_boards.md#enabling-deploy-boards) +is required to use Logs. ## Usage @@ -30,7 +42,8 @@ You can access them in two ways. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5. -Go to **{cloud-gear}** **Operations > Logs** on the sidebar menu. +Go to **{cloud-gear}** **Operations > Pod logs** on the sidebar menu to display +the **Log Explorer**.  @@ -38,34 +51,42 @@ Go to **{cloud-gear}** **Operations > Logs** on the sidebar menu. Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): -1. Go to **{cloud-gear}** **Operations > Environments** and find the environment which contains the desired pod, like `production`. -1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). -1. When mousing over the list of pods, a tooltip will appear with the exact pod name and status. +1. Go to **{cloud-gear}** **Operations > Environments** and find the environment + which contains the desired pod, like `production`. +1. On the **Environments** page, you should see the status of the environment's + pods with [Deploy Boards](../deploy_boards.md). +1. When mousing over the list of pods, a tooltip will appear with the exact pod name + and status.  -1. Click on the desired pod to bring up the logs view. +1. Click on the desired pod to display the **Log Explorer**. ### Logs view -The logs view lets you filter the logs by: +The **Log Explorer** lets you filter the logs by: - Pods. - [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. -- [From GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656), [full text search](#full-text-search). +- [From GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656), + [full text search](#full-text-search). - [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/197879), dates. -Loading more than 500 log lines is possible from [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198050) onwards. +Loading more than 500 log lines is possible from +[GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198050) onward. -Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/13404). +Support for pods with multiple containers is coming +[in a future release](https://gitlab.com/gitlab-org/gitlab/issues/13404). -Support for historical data is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/196191). +Support for historical data is coming +[in a future release](https://gitlab.com/gitlab-org/gitlab/issues/196191). ### Filter by date > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/197879) in GitLab 12.8. -When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, you can filter by date. +When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) +on your cluster, you can filter logs displayed in the **Log Explorer** by date. -Click on **Show last** to see the available options. +Click **Show last** in the **Log Explorer** to see the available options. ### Full text search @@ -74,7 +95,8 @@ Click on **Show last** to see the available options. When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, you can search the content of your logs through a search bar. -The search is passed on to Elasticsearch using the [simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) +The search is passed on to Elasticsearch using the +[simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) Elasticsearch function, which supports the following operators: | Operator | Description | diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 5575cd1d2d4..dfed43470bc 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,14 +1,19 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Runbooks Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, or troubleshooting a particular system. -Using [Jupyter Notebooks](https://jupyter.org/) and the [Rubix library](https://github.com/Nurtch/rubix), +Using [Jupyter Notebooks](https://jupyter.org/) and the +[Rubix library](https://github.com/Nurtch/rubix), users can get started writing their own executable runbooks. -## Overview - Historically, runbooks took the form of a decision tree or a detailed step-by-step guide depending on the condition or system. @@ -22,121 +27,128 @@ pre-written code blocks or database queries against a given environment. The JupyterHub app offered via GitLab’s Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps -runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it -simple to create common Kubernetes and AWS workflows, you can also create them manually without -Rubix. +runbooks. A sample runbook is provided, showcasing common operations. While +Rubix makes it simple to create common Kubernetes and AWS workflows, you can +also create them manually without Rubix. -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) -for an overview of how this is accomplished in GitLab!** +for an overview of how this is accomplished in GitLab! ## Requirements To create an executable runbook, you will need: -1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. - The simplest way to get started is to add a cluster using one of [GitLab's integrations](../add_remove_clusters.md#create-new-cluster). -1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install - all the other applications. It is installed in its own pod inside the cluster which - can run the Helm CLI in a safe environment. -1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based - virtual hosting. It acts as a web proxy for your applications. -1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across - a team. Jupyter Notebooks provide a web-based interactive programming environment - used for data analysis, visualization, and machine learning. +- **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the + applications. The simplest way to get started is to add a cluster using one + of [GitLab's integrations](../add_remove_clusters.md#create-new-cluster). +- **Helm Tiller** - Helm is a package manager for Kubernetes and is required to + install all the other applications. It's installed in its own pod inside the + cluster which can run the Helm CLI in a safe environment. +- **Ingress** - Ingress can provide load balancing, SSL termination, and name-based + virtual hosting. It acts as a web proxy for your applications. +- **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user + service for managing notebooks across a team. Jupyter Notebooks provide a + web-based interactive programming environment used for data analysis, + visualization, and machine learning. ## Nurtch -Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is -an open-source Python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. -Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified -down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest/) -for more information. +Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). +Rubix is an open-source Python library that makes it easy to perform common +DevOps tasks inside Jupyter Notebooks. Tasks such as plotting Cloudwatch metrics +and rolling your ECS/Kubernetes app are simplified down to a couple of lines of +code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest/) for more +information. ## Configure an executable runbook with GitLab Follow this step-by-step guide to configure an executable runbook in GitLab using -the components outlined above and the preloaded demo runbook. - -### 1. Add a Kubernetes cluster - -Follow the steps outlined in [Create new cluster](../add_remove_clusters.md#create-new-cluster) -to add a Kubernetes cluster to your project. - -### 2. Install Helm Tiller, Ingress, and JupyterHub - -Once the cluster has been provisioned in GKE, click the **Install** button next to the **Helm Tiller** app. - - +the components outlined above and the pre-loaded demo runbook. -Once Tiller has been installed successfully, click the **Install** button next to the **Ingress** app. +1. Add a Kubernetes cluster to your project by following the steps outlined in + [Create new cluster](../add_remove_clusters.md#create-new-cluster). +1. After the cluster has been provisioned in GKE, click the **Install** button + next to the **Helm Tiller** application to install Helm Tiller. - +  -Once Ingress has been installed successfully, click the **Install** button next to the **JupyterHub** app. +1. After Helm Tiller has been installed successfully, click the **Install** button next + to the **Ingress** application. - +  -### 3. Login to JupyterHub and start the server +1. After Ingress has been installed successfully, click the **Install** button next + to the **JupyterHub** application. You will need the **Jupyter Hostname** provided + here in the next step. -Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click -**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This -will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**. +  - +1. After JupyterHub has been installed successfully, open the **Jupyter Hostname** + in your browser. Click the **Sign in with GitLab** button to log in to + JupyterHub and start the server. Authentication is enabled for any user of the + GitLab instance with OAuth2. This button redirects you to a page at GitLab + requesting authorization for JupyterHub to use your GitLab account. -Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. -The server will take a couple of seconds to start. +  -### 4. Configure access +1. Click **Authorize**, and you will be redirected to the JupyterHub application. +1. Click **Start My Server**, and the server will start in a few seconds. +1. To configure the runbook's access to your GitLab project, you must enter your + [GitLab Access Token](../../../profile/personal_access_tokens.md) + and your Project ID in the **Setup** section of the demo runbook: -In order for the runbook to access your GitLab project, you will need to enter a -[GitLab Access Token](../../../profile/personal_access_tokens.md) -as well as your Project ID in the **Setup** section of the demo runbook. + 1. Double-click the **DevOps-Runbook-Demo** folder located on the left panel. -Double-click the **DevOps-Runbook-Demo** folder located on the left panel. +  - + 1. Double-click the `Nurtch-DevOps-Demo.ipynb` runbook. -Double-click the "Nurtch-DevOps-Demo.ipynb" runbook. +  - + Jupyter displays the runbook's contents in the right-hand side of the screen. + The **Setup** section displays your `PRIVATE_TOKEN` and your `PROJECT_ID`. + Enter these values, maintaining the single quotes as follows: -The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find -entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID`. Enter both these values, conserving the single quotes as follows: + ```sql + PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' + PROJECT_ID = '1234567' + ``` -```sql -PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' -PROJECT_ID = '1234567' -``` + 1. Update the `VARIABLE_NAME` on the last line of this section to match the name of + the variable you're using for your access token. In this example, our variable + name is `PRIVATE_TOKEN`. -Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your -access token. In this example our variable name is `PRIVATE_TOKEN`. + ```sql + VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value + ``` -```sql -VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value -``` +1. To configure the operation of a runbook, create and configure variables: -### 5. Configure an operation + NOTE: **Note:** + 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: -For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query -a PostgreSQL database. The first 4 lines of the section define the variables that are required for this query to function. + ```sql + %env DB_USER={project.variables.get('DB_USER').value} + %env DB_PASSWORD={project.variables.get('DB_PASSWORD').value} + %env DB_ENDPOINT={project.variables.get('DB_ENDPOINT').value} + %env DB_NAME={project.variables.get('DB_NAME').value} + ``` -```sql -%env DB_USER={project.variables.get('DB_USER').value} -%env DB_PASSWORD={project.variables.get('DB_PASSWORD').value} -%env DB_ENDPOINT={project.variables.get('DB_ENDPOINT').value} -%env DB_NAME={project.variables.get('DB_NAME').value} -``` + 1. Navigate to **{settings}** **Settings >> CI/CD >> Variables** to create + the variables in your project. -Create the matching variables in your project's **Settings >> CI/CD >> Variables** +  - + 1. Click **Save variables**. -Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be -displayed in-line as follows: + 1. In Jupyter, click the **Run SQL queries in Notebook** heading, and then click + **Run**. The results are displayed inline as follows: - +  -You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the +You can try other operations, such as running shell scripts or interacting with a +Kubernetes cluster. Visit the [Nurtch Documentation](http://docs.nurtch.com/) for more information. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 3df57e3a7a5..124a0d4bf9f 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Deploying AWS Lambda function using GitLab CI/CD GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. @@ -150,7 +156,7 @@ endpoints: 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 diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 418e16aa0c1..2156d96f92a 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Serverless > Introduced in GitLab 11.5. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 49083be77dc..45d9e8f04e0 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -9,6 +9,33 @@ in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. > - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/issues/53182) added in GitLab Starter 12.1. > - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. +## Introduction + +When contributing to a project, it can often be difficult +to find out who should review or approve merge requests. +Additionally, if you have a question over a specific file or +code block, it may be difficult to know who to find the answer from. + +GitLab Code Owners is a feature to define who owns specific +files or paths in a repository, allowing other users to understand +who is responsible for each file or path. + +## Why is this useful? + +Code Owners allows for a version controlled single source of +truth file outlining the exact GitLab users or groups that +own certain files or paths in a repository. Code Owners can be +utilized in the merge request approval process which can streamline +the process of finding the right reviewers and approvers for a given +merge request. + +In larger organizations or popular open source projects, Code Owners +can also be useful to understand who to contact if you have +a question that may not be related to code review or a merge request +approval. + +## How to set up Code Owners + You can use a `CODEOWNERS` file to specify users or [shared groups](members/share_project_with_groups.md) that are responsible for certain files in a repository. @@ -41,7 +68,7 @@ The user that would show for `README.md` would be `@user2`. ## Approvals by Code Owners Once you've set Code Owners to a project, you can configure it to -receive approvals: +be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)** @@ -50,6 +77,9 @@ Once set, Code Owners are displayed in merge requests widgets:  +NOTE: **Note**: + While the`CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules) it can also be used as the sole driver of a Merge Request approval (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)) by simply creating the file in one of the three locations specified above, configuring the Code Owners to be required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium) and then using [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) to specify the actual owners and granular permissions. + ## The syntax of Code Owners files Files can be specified using the same kind of patterns you would use @@ -69,23 +99,28 @@ escaped using `\#` to address files for which the name starts with a Example `CODEOWNERS` file: ```plaintext -# This is an example code owners file, lines starting with a `#` will -# be ignored. +# This is an example of a code owners file +# lines starting with a `#` will be ignored. # app/ @commented-rule # We can specify a default match using wildcards: * @default-codeowner +# We can also specify "multiple tab or space" separated codeowners: +* @multiple @code @owners + # Rules defined later in the file take precedence over the rules # defined before. # This will match all files for which the file name ends in `.rb` *.rb @ruby-owner -# Files with a `#` can still be accesssed by escaping the pound sign +# Files with a `#` can still be accessed by escaping the pound sign \#file_with_pound.rb @owner-file-with-pound # Multiple codeowners can be specified, separated by spaces or tabs +# In the following case the CODEOWNERS file from the root of the repo +# has 3 code owners (@multiple @code @owners) CODEOWNERS @multiple @code @owners # Both usernames or email addresses can be used to match diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index c479f610ff1..8f7bb844e37 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -3,7 +3,7 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. GitLab's Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../ci/environments.md) running on [Kubernetes](https://kubernetes.io), displaying the status +status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -57,9 +57,9 @@ specific environment, there are a lot of use cases. To name a few: ## Enabling Deploy Boards -To display the Deploy Boards for a specific [environment](../../ci/environments.md) you should: +To display the Deploy Boards for a specific [environment](../../ci/environments/index.md) you should: -1. Have [defined an environment](../../ci/environments.md#defining-environments) with a deploy stage. +1. Have [defined an environment](../../ci/environments/index.md#defining-environments) with a deploy stage. 1. Have a Kubernetes cluster up and running. @@ -113,7 +113,7 @@ metadata: name: "APPLICATION_NAME" annotations: app.gitlab.com/app: ${CI_PROJECT_PATH_SLUG} - app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} + app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} spec: replicas: 1 selector: @@ -130,6 +130,11 @@ spec: The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. +NOTE: **Note:** +The YAML file is static. If you apply it using `kubectl apply`, you must +manually provide the project and environment slugs, or create a script to +replace the variables in the YAML before applying. + ## Canary Deployments A popular CI strategy, where a small portion of the fleet is updated to the new @@ -141,5 +146,5 @@ version of your application. - [GitLab Autodeploy](../../topics/autodevops/stages.md#auto-deploy) - [GitLab CI/CD environment variables](../../ci/variables/README.md) -- [Environments and deployments](../../ci/environments.md) +- [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ebb12a6ed5d..2d42debed68 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -3,8 +3,10 @@ > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/199370) from **Settings > Repository** in GitLab 12.9. > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. +> - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) from **Settings > CI / CD** in GitLab 13.0. -Deploy tokens allow you to download (`git clone`) or push and pull the container registry images of a project without having a user and a password. +Deploy tokens allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. Deploy tokens can be managed by [maintainers only](../../permissions.md). @@ -16,7 +18,7 @@ You can create as many deploy tokens as you like from the settings of your proje 1. Log in to your GitLab account. 1. Go to the project (or group) you want to create Deploy Tokens for. -1. Go to **{settings}** **Settings** > **CI / CD**. +1. Go to **{settings}** **Settings** > **Repository**. 1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). @@ -65,7 +67,7 @@ To download a repository using a Deploy Token, you just need to: 1. `git clone` the project using the Deploy Token: ```shell - git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git + git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git ``` Replace `<username>` and `<deploy_token>` with the proper values. @@ -100,6 +102,22 @@ To push the container registry images, you'll need to: Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply push images to your Container Registry. +### Read or pull packages + +To pull packages in the GitLab package registry, you'll need to: + +1. Create a Deploy Token with `read_package_registry` as a scope. +1. Take note of your `username` and `token`. +1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. + +### Push or upload packages + +To upload packages in the GitLab package registry, you'll need to: + +1. Create a Deploy Token with `write_package_registry` as a scope. +1. Take note of your `username` and `token`. +1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. + ### Group Deploy Token > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/21765) in GitLab 12.9. @@ -107,6 +125,9 @@ push images to your Container Registry. A deploy token created at the group level can be used across all projects that belong either to the specific group or to one of its subgroups. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks). + To use a group deploy token: 1. [Create](#creating-a-deploy-token) a deploy token for a group. @@ -132,3 +153,6 @@ those variables: ```shell docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` + +NOTE: **Note:** +The special handling for the `gitlab-deploy-token` deploy token is not currently implemented for group deploy tokens. For the deploy token to be available for CI/CD jobs, it must be created at the project level. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) for details. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index a02dc016f03..16ac53a2b52 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -39,6 +39,26 @@ templates of the default branch will be taken into account. Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` directory in your repository. Commit and push to your default branch. +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`. + 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. + +To create the `.gitlab/issue_templates` directory: + + 1. Click the `+` button next to `master` and select **New directory**. + 1. Name this new directory `.gitlab` and commit to your default branch. + 1. Click the `+` button next to `master` again and select **New directory**.This time, n + 1. Name your directory `issue_templates` and commit to your default branch. + +To check if this has worked correctly, [create a new issue](./issues/managing_issues.md#create-a-new-issue) +and see if you can choose a description template. + ## Creating merge request templates Similarly to issue templates, create a new Markdown (`.md`) file inside the diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index d5f35051e9a..9069a231db4 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -2,9 +2,10 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9. -File Locking helps you avoid merge conflicts and better manage your binary files. -Lock any file or directory, make your changes, and then unlock it so another -member of the team can edit it. +Working with multiple people on the same file can be a risk. Conflicts when merging a non-text file are hard to overcome and will require a lot of manual work to resolve. File Locking helps you avoid these merge conflicts and better manage your binary files. + +With File Locking, you can lock any file or directory, make your changes, and +then unlock it so another member of the team can edit it. ## Overview diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 21ef94e61f7..260e618ba03 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,6 +1,6 @@ # Git Attributes -GitLab supports defining custom [Git attributes][gitattributes] such as what +GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting diffs. @@ -18,5 +18,3 @@ ignored. The `.gitattributes` file can be used to define which language to use when syntax highlighting files and diffs. See ["Syntax Highlighting"](highlighting.md) for more information. - -[gitattributes]: https://git-scm.com/docs/gitattributes diff --git a/doc/user/project/img/service_desk_custom_email_address_v13_0.png b/doc/user/project/img/service_desk_custom_email_address_v13_0.png Binary files differnew file mode 100644 index 00000000000..6ce8bf45085 --- /dev/null +++ b/doc/user/project/img/service_desk_custom_email_address_v13_0.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 77fc2761e07..56717858b53 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -24,7 +24,7 @@ Import your projects from Bitbucket Cloud to GitLab with minimal effort. ## Requirements -The [Bitbucket Cloud integration][bb-import] must be first enabled in order to be +The [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be first enabled in order to be able to import your projects from Bitbucket Cloud. Ask your GitLab administrator to enable this if not already. @@ -42,7 +42,7 @@ The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's namespace that started the import process. -## Importing your Bitbucket repositories +## Import your Bitbucket repositories 1. Sign in to GitLab and go to your dashboard. 1. Click on **New project**. @@ -61,5 +61,11 @@ namespace that started the import process.  -[bb-import]: ../../../integration/bitbucket.md -[social sign-in]: ../../profile/account/social_sign_in.md +## Troubleshooting + +If you have more than one Bitbucket account, be sure to sign in to the correct account. +If you've accidentally started the import process with the wrong account, follow these steps: + +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. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 99179c3190e..55df2d7294d 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -73,3 +73,7 @@ namespace that started the import process. imported.  + +## Troubleshooting + +See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index db8d33b58da..4c213f21920 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -8,7 +8,7 @@ your self-managed GitLab instance. NOTE: **Note:** These instructions work for users on GitLab.com, but if you are an administrator of a self-managed GitLab instance or if you are importing from GitHub Enterprise, -you must enable [GitHub integration][gh-import]. GitHub integration is the only method for +you must enable [GitHub integration](../../../integration/github.md). GitHub integration is the only method for importing from GitHub Enterprise. If you are using GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#using-a-github-token), but this method is not recommended because it cannot associate all user activity @@ -81,7 +81,7 @@ the user account that is performing the import. NOTE: **Note:** If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured -[GitHub integration][gh-import]. +[GitHub integration](../../../integration/github.md). 1. From the top navigation bar, click **+** and select **New project**. 1. Select the **Import project** tab and then select **GitHub**. @@ -155,5 +155,3 @@ servers. For 4 servers with 8 cores this means you can import up to 32 objects ( Reducing the time spent in cloning a repository can be done by increasing network throughput, CPU capacity, and disk performance (e.g., by using high performance SSDs) of the disks that store the Git repositories (for your GitLab instance). Increasing the number of Sidekiq workers will *not* reduce the time spent cloning repositories. - -[gh-import]: ../../../integration/github.md "GitHub integration" diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 49224001fe6..db48282a8f3 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -9,6 +9,15 @@ Jira issues import is an MVC, project-level feature, meaning that issues from mu Jira projects can be imported into a GitLab project. MVC version imports issue title and description as well as some other issue metadata as a section in the issue description. +## Future iterations + +As of GitLab 12.10, the Jira issue importer only brings across the title and description of +an issue. + +There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the +addition of items such as issue assignees, labels, comments, user mapping, and much more. +These will be included in the future iterations of the GitLab Jira importer. + ## Prerequisites ### Permissions diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 585c45e35df..50272f0e007 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -242,7 +242,7 @@ field. For example: -```text +```plaintext machine example.gitlab.com login <gitlab_user_name> password <personal_access_token> diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 8c7e6edbf38..db8f24fc1e1 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -27,7 +27,7 @@ need to be configured in a Bamboo build plan before GitLab can integrate. 1. In the left pane, select a build stage. If you have multiple build stages you want to select the last stage that contains the Git checkout task. 1. Select the 'Miscellaneous' tab. -1. Under 'Pattern Match Labelling' put `${bamboo.repository.revision.number}` +1. Under 'Pattern Match Labeling' put `${bamboo.repository.revision.number}` in the 'Labels' box. 1. Save diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 1a000fd1c44..2234727dd82 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: Health +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Generic alerts integration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. @@ -26,12 +32,16 @@ You can customize the payload by sending the following parameters. All fields ar | Property | Type | Description | | -------- | ---- | ----------- | -| `title` | String | The title of the incident. If none is provided, then `New: Incident #N` will be used, where `#N` is the number of incident | +| `title` | String | The title of the incident. Required. | | `description` | String | A high-level summary of the problem. | | `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. | | `service` | String | The affected service. | | `monitoring_tool` | String | The name of the associated monitoring tool. | | `hosts` | String or Array | One or more hosts, as to where this incident occurred. | +| `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. | + +TIP: **Payload size:** +Ensure your requests are smaller than the [payload application limits](../../../administration/instance_limits.md#generic-alert-json-payloads). Example request: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 1ef2f593621..49b6a3f6450 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,13 +1,14 @@ # GitLab Slack application **(FREE ONLY)** +> - Introduced in GitLab 9.4. +> - Distributed to Slack App Directory in GitLab 10.2. + NOTE: **Note:** The GitLab Slack application is only configurable for GitLab.com. It will **not** work for on-premises installations where you can configure the [Slack slash commands](slack_slash_commands.md) service instead. We're planning to make this configurable for all GitLab installations, but there's no ETA - see [#28164](https://gitlab.com/gitlab-org/gitlab/issues/28164). -It was first introduced in GitLab 9.4 and distributed to Slack App Directory in -GitLab 10.2. Slack provides a native application which you can enable via your project's integrations on GitLab.com. @@ -35,12 +36,30 @@ docs on [Adding an app to your team](https://slack.com/help/articles/202035138). To enable GitLab's service for your Slack team: -1. Go to your project's **Settings > Integration > Slack application** (only - visible on GitLab.com) -1. Click the "Add to Slack" button +1. Go to your project's **{settings}** **Settings > Integration > Slack application** (only + visible on GitLab.com). +1. Click **Add to Slack**. That's all! You can now start using the Slack slash commands. +## Create a project alias for Slack + +To create a project alias on GitLab.com for Slack integration: + +1. Go to your project's home page. +1. Navigate to **{settings}** **Settings > Integrations** (only visible on GitLab.com) +1. On the **Integrations** page, click **Slack application**. +1. The current **Project Alias**, if any, is displayed. To edit this value, + click **Edit**. +1. Enter your desired alias, and click **Save changes**. + +Some Slack commands require a project alias, and fail with the following error +if the project alias is incorrect or missing from the command: + +```plaintext +GitLab error: project or alias not found +``` + ## Usage After confirming the installation, you, and everyone else in your Slack team, diff --git a/doc/user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png b/doc/user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png Binary files differnew file mode 100644 index 00000000000..a042fbbcf4e --- /dev/null +++ b/doc/user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png diff --git a/doc/user/project/integrations/img/panel_context_menu_v12_10.png b/doc/user/project/integrations/img/panel_context_menu_v12_10.png Binary files differdeleted file mode 100644 index 096262fea91..00000000000 --- a/doc/user/project/integrations/img/panel_context_menu_v12_10.png +++ /dev/null diff --git a/doc/user/project/integrations/img/panel_context_menu_v13_0.png b/doc/user/project/integrations/img/panel_context_menu_v13_0.png Binary files differnew file mode 100644 index 00000000000..2d7cb923981 --- /dev/null +++ b/doc/user/project/integrations/img/panel_context_menu_v13_0.png diff --git a/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png b/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png Binary files differnew file mode 100644 index 00000000000..2f0309ce664 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_select_v_13_0.png diff --git a/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png b/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png Binary files differnew file mode 100644 index 00000000000..59dc9ccfd30 --- /dev/null +++ b/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png diff --git a/doc/user/project/integrations/img/webex_teams_configuration.png b/doc/user/project/integrations/img/webex_teams_configuration.png Binary files differnew file mode 100644 index 00000000000..66993e0887d --- /dev/null +++ b/doc/user/project/integrations/img/webex_teams_configuration.png diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index a23d8d7306d..6a202c9a130 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -17,21 +17,21 @@ If you have the Omnibus GitLab package installed, Mattermost is already bundled in it. All you have to do is configure it. Read more in the [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). -## Automated Configuration +## Automated configuration If Mattermost is installed on the same server as GitLab, the configuration process can be done for you by GitLab. Go to the Mattermost Slash Command service on your project and click the 'Add to Mattermost' button. -## Manual Configuration +## Manual configuration The configuration consists of two parts. First you need to enable the slash commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost -This step is only required when using a source install, omnibus installs will be +This step is only required when using a source install, Omnibus installs will be preconfigured with the right settings. The first thing to do in Mattermost is to enable custom slash commands from @@ -145,6 +145,15 @@ trigger word followed by <kbd>help</kbd>. Example: `/gitlab help` The permissions to run the [available commands](#available-slash-commands) derive from the [permissions you have on the project](../../permissions.md#project-members-permissions). +## Troubleshooting + +If an event is not being triggered, confirm that the channel you're using is a public one, as +Mattermost webhooks do not have access to private channels. + +If a private channel is required, you can edit the webhook's channel in Mattermost and +select a private channel. It is not possible to use different channels for +different types of notifications - all events will be sent to the specified channel. + ## Further reading - [Mattermost slash commands documentation](https://docs.mattermost.com/developer/slash-commands.html) diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index b973abbe210..88668ab6c7d 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -47,7 +47,7 @@ Click on the service links to see further configuration instructions and details | [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 | | Pipelines emails | Email the pipeline status to a list of recipients | No | -| [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | 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 | | [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application | No | | PivotalTracker | Project Management Software (Source Commits Endpoint) | No | @@ -55,6 +55,7 @@ Click on the service links to see further configuration instructions and details | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | | [Redmine](redmine.md) | Redmine issue tracker | No | | [Unify Circuit](unify_circuit.md) | Receive events notifications in Unify Circuit | No | +| [Webex Teams](webex_teams.md) | Receive events notifications in Webex Teams | No | | [YouTrack](youtrack.md) | YouTrack issue tracker | No | ## Push hooks limit @@ -93,6 +94,15 @@ From this page, you can repeat delivery with the same data by clicking **Resend  +### Uninitialized repositories + +Some integrations fail with an error `Test Failed. Save Anyway` when you attempt to set them up on +uninitialized repositories. This is because the default service test uses push data to build the +payload for the test request, and it fails, because there are no push events for the project. + +To resolve this error, initialize the repository by pushing a test file to the project and set up +the integration again. + ## Contributing to integrations Because GitLab is open source we can ship with the code and tests for all @@ -100,9 +110,6 @@ plugins. This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. For an overview of what integrations are available, please see the -[project_services source directory][projects-code]. +[project_services source directory](https://gitlab.com/gitlab-org/gitlab/tree/master/app/models/project_services). Contributions are welcome! - -[projects-code]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/models/project_services -[permissions]: ../../permissions.md diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index bbed14ea93f..6c40e5b9696 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Prometheus integration > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. @@ -66,6 +72,25 @@ It enables you to search as you type through all environments and select the one  +##### Select a dashboard + +The **dashboard** dropdown box above the dashboard displays the list of all dashboards available for the project. +It enables you to search as you type through all dashboards and select the one you're looking for. + + + +##### Mark a dashboard as favorite + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214582) in GitLab 13.0. + +When viewing a dashboard, click the empty **Star dashboard** **{star-o}** button to mark a +dashboard as a favorite. Starred dashboards display a solid star **{star}** button, +and appear at the top of the dashboard select list. + +To remove dashboard from the favorites list, click the solid **Unstar Dashboard** **{star}** button. + + + #### About managed Prometheus deployments Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). @@ -93,7 +118,7 @@ Integration with Prometheus requires the following: #### Getting started -Installing and configuring Prometheus to monitor applications is fairly straight forward. +Installing and configuring Prometheus to monitor applications is fairly straightforward. 1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 1. Set up one of the [supported monitoring targets](prometheus_library/index.md) @@ -123,14 +148,32 @@ to integrate with. 1. Provide the domain name or IP address of your server, for example `http://thanos.example.com/` or `http://192.0.2.1/`. 1. Click **Save changes**. +### Precedence with multiple Prometheus configurations + +Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) +and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, only +one of them will be used: + +- If you have enabled a + [Prometheus manual configuration](#manual-configuration-of-prometheus) + and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes), + the manual configuration takes precedence and is used to run queries from + [dashboards](#defining-custom-dashboards-per-project) and [custom metrics](#adding-custom-metrics). +- If you have managed Prometheus applications installed on Kubernetes clusters + at **different** levels (project, group, instance), the order of precedence is described in + [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). +- If you have managed Prometheus applications installed on multiple Kubernetes + clusters at the **same** level, the Prometheus application of a cluster with a + matching [environment scope](../../../ci/environments/index.md#scoping-environments-with-specs) is used. + ## Monitoring CI/CD Environments Once configured, GitLab will attempt to retrieve performance metrics for any environment which has had a successful deployment. -GitLab will automatically scan the Prometheus server for metrics from known servers like Kubernetes and NGINX, and attempt to identify individual environment. The supported metrics and scan process is detailed in our [Prometheus Metrics Library documentation](prometheus_library/index.md). +GitLab will automatically scan the Prometheus server for metrics from known servers like Kubernetes and NGINX, and attempt to identify individual environments. The supported metrics and scan process is detailed in our [Prometheus Metrics Library documentation](prometheus_library/index.md). -You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). +You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments/index.md#monitoring-environments). ### Adding custom metrics @@ -152,10 +195,12 @@ A few fields are required: - **Y-axis label**: Y axis title to display on the dashboard. - **Unit label**: Query units, for example `req / sec`. Shown next to the value. -Multiple metrics can be displayed on the same chart if the fields **Name**, **Type**, and **Y-axis label** match between metrics. For example, a metric with **Name** `Requests Rate`, **Type** `Business`, and **Y-axis label** `rec / sec` would display on the same chart as a second metric with the same values. A **Legend label** is suggested if this feature used. +Multiple metrics can be displayed on the same chart if the fields **Name**, **Type**, and **Y-axis label** match between metrics. For example, a metric with **Name** `Requests Rate`, **Type** `Business`, and **Y-axis label** `rec / sec` would display on the same chart as a second metric with the same values. A **Legend label** is suggested if this feature is used. #### Query Variables +##### Predefined variables + GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are: - `ci_environment_slug` @@ -168,10 +213,34 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) NOTE: **Note:** Variables for Prometheus queries must be lowercase. -There are 2 methods to specify a variable in a query or dashboard: +##### User-defined variables + +[Variables can be defined](#templating-templating-properties) in a custom dashboard YAML file. + +##### Using variables + +Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7). + +Support for the `"%{ci_environment_slug}"` format was +[removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0. +Queries that continue to use the old format will show no data. + +#### Query Variables from URL -1. Variables can be specified using the [Liquid template format](https://shopify.dev/docs/liquid/reference/basics), for example `{{ci_environment_slug}}` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.6). -1. You can also enclose it in quotation marks with curly braces with a leading percent, for example `"%{ci_environment_slug}"`. This method is deprecated though and support will be [removed in the next major release](https://gitlab.com/gitlab-org/gitlab/issues/37990). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214500) in GitLab 13.0. + +GitLab supports setting custom variables through URL parameters. Surround the variable +name with double curly braces (`{{example}}`) to interpolate the variable in a query: + +```plaintext +avg(sum(container_memory_usage_bytes{container_name!="{{pod}}"}) by (job)) without (job) /1024/1024/1024' +``` + +The URL for this query would be: + +```plaintext +http://gitlab.com/<user>/<project>/-/environments/<environment_id>/metrics?dashboard=.gitlab%2Fdashboards%2Fcustom.yml&pod=POD +``` #### Editing additional metrics from the dashboard @@ -261,19 +330,29 @@ If you select another branch, this branch should be merged to your **default** b Dashboards have several components: -- Panel groups, which comprise of panels. +- Templating variables. +- Panel groups, which consist of panels. - Panels, which support one or more metrics. The following tables outline the details of expected properties. -**Dashboard properties:** +##### **Dashboard (top-level) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | | `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | | `panel_groups` | array | yes | The panel groups which should be on the dashboard. | +| `templating` | Hash | no | Top level key under which templating related options can be added. | + +##### **Templating (`templating`) properties** + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `variables` | Hash | no | Variables can be defined here. | -**Panel group (`panel_groups`) properties:** +Read the documentation on [templating](#templating-variables-for-metrics-dashboards). + +##### **Panel group (`panel_groups`) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | @@ -281,7 +360,7 @@ The following tables outline the details of expected properties. | `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `panels` | array | required | The panels which should be in the panel group. | -**Panel (`panels`) properties:** +##### **Panel (`panels`) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | @@ -293,19 +372,19 @@ The following tables outline the details of expected properties. | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | -**Axis (`panels[].y_axis`) properties:** +##### **Axis (`panels[].y_axis`) properties** -| Property | Type | Required | Description | -| ----------- | ------ | ------------------------- | -------------------------------------------------------------------- | -| `name` | string | no, but highly encouraged | Y-Axis label for the panel, it will replace `y_label` if set. | -| `format` | string | no, defaults to `number` | Unit format used. See the [full list of units](prometheus_units.md). | -| `precision` | number | no, defaults to `2` | Number of decimals to display in the number. | +| Property | Type | Required | Description | +| ----------- | ------ | ----------------------------- | -------------------------------------------------------------------- | +| `name` | string | no, but highly encouraged | Y-Axis label for the panel. Replaces `y_label` if set. | +| `format` | string | no, defaults to `engineering` | Unit format used. See the [full list of units](prometheus_units.md). | +| `precision` | number | no, defaults to `2` | Number of decimal places to display in the number. | | -**Metrics (`metrics`) properties:** +##### **Metrics (`metrics`) properties** | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | -| `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/60319)). | +| `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/27980)). | | `unit` | string | yes | Defines the unit of the query's return data. | | `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. Can contain time series labels as interpolated variables. | | `query` | string | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | @@ -610,21 +689,122 @@ Note the following properties:  +### Templating variables for metrics dashboards + +Templating variables can be used to make your metrics dashboard more versatile. + +#### Templating variable types + +`templating` is a top-level key in the +[dashboard YAML](#dashboard-top-level-properties). +Define your variables in the `variables` key, under `templating`. The value of +the `variables` key should be a hash, and each key under `variables` +defines a templating variable on the dashboard. + +A variable can be used in a Prometheus query in the same dashboard using the syntax +described [here](#using-variables). + +##### `text` variable type + +CAUTION: **Warning:** +This variable type is an _alpha_ feature, and is subject to change at any time +without prior notice! + +For each `text` variable defined in the dashboard YAML, there will be a free text +box on the dashboard UI, allowing you to enter a value for each variable. + +The `text` variable type supports a simple and a full syntax. + +###### Simple syntax + +This example creates a variable called `variable1`, with a default value +of `default value`: + +```yaml +templating: + variables: + variable1: 'default value' # `text` type variable with `default value` as its default. +``` + +###### Full syntax + +This example creates a variable called `variable1`, with a default value of `default`. +The label for the text box on the UI will be the value of the `label` key: + +```yaml +templating: + variables: + variable1: # The variable name that can be used in queries. + label: 'Variable 1' # (Optional) label that will appear in the UI for this text box. + type: text + options: + default_value: 'default' # (Optional) default value. +``` + +##### `custom` variable type + +CAUTION: **Warning:** +This variable type is an _alpha_ feature, and is subject to change at any time +without prior notice! + +Each `custom` variable defined in the dashboard YAML creates a dropdown +selector on the dashboard UI, allowing you to select a value for each variable. + +The `custom` variable type supports a simple and a full syntax. + +###### Simple syntax + +This example creates a variable called `variable1`, with a default value of `value1`. +The dashboard UI will display a dropdown with `value1`, `value2` and `value3` +as the choices. + +```yaml +templating: + variables: + variable1: ['value1', 'value2', 'value3'] +``` + +###### Full syntax + +This example creates a variable called `variable1`, with a default value of `var1_option_2`. +The label for the text box on the UI will be the value of the `label` key. +The dashboard UI will display a dropdown with `Option 1` and `Option 2` +as the choices. + +If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`. +Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`: + +```yaml +templating: + variables: + variable1: # The variable name that can be used in queries. + label: 'Variable 1' # (Optional) label that will appear in the UI for this dropdown. + type: custom + options: + values: + - value: 'value option 1' # The value that will replace the variable in queries. + text: 'Option 1' # (Optional) Text that will appear in the UI dropdown. + - value: 'value_option_2' + text: 'Option 2' + default: true # (Optional) This option should be the default value of this variable. +``` + ### View and edit the source file of a custom dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. When viewing a custom dashboard of a project, you can view the original -`.yml` file by clicking on **Edit dashboard** button. +`.yml` file by clicking on the **Edit dashboard** button. ### Chart Context Menu From each of the panels in the dashboard, you can access the context menu by clicking the **{ellipsis_v}** **More actions** dropdown box above the upper right corner of the panel to take actions related to the chart's data. - + The options are: +- [Expand panel](#expand-panel) - [View logs](#view-logs-ultimate) - [Download CSV](#downloading-data-as-csv) - [Copy link to chart](#embedding-gitlab-managed-kubernetes-metrics) @@ -632,7 +812,8 @@ The options are: ### Dashboard Annotations -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/215224) in GitLab 13.0. You can use **Metrics Dashboard Annotations** to mark any important events on every metrics dashboard by adding annotations to it. While viewing a dashboard, @@ -644,6 +825,18 @@ its description. You can create annotations by making requests to the [Metrics dashboard annotations API](../../../api/metrics_dashboard_annotations.md) + + +### Expand panel + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0. + +To view a larger version of a visualization, expand the panel by clicking the +**{ellipsis_v}** **More actions** icon and selecting **Expand panel**. + +To return to the metrics dashboard, click the **Back** button in your +browser, or pressing the <kbd>Esc</kbd> key. + ### View Logs **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/122013) in GitLab 12.8. @@ -708,14 +901,14 @@ receivers: ... ``` -In order for GitLab to associate your alerts with an [environment](../../../ci/environments.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. +In order for GitLab to associate your alerts with an [environment](../../../ci/environments/index.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. ### Taking action on incidents **(ULTIMATE)** >- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. >- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. -Alerts can be used to trigger actions, like open an issue automatically (enabled by default since `12.1`). To configure the actions: +Alerts can be used to trigger actions, like opening an issue automatically (enabled by default since `12.1`). To configure the actions: 1. Navigate to your project's **Settings > Operations > Incidents**. 1. Enable the option to create issues. @@ -734,7 +927,7 @@ Once enabled, an issue will be opened automatically when an alert is triggered w - Optional list of attached annotations extracted from `annotations/*` - Alert [GFM](../../markdown.md): GitLab Flavored Markdown from `annotations/gitlab_incident_markdown` -When GitLab receives a **Recovery Alert**, it will automatically close the associated issue. This action will be recorded as a system message on the issue indicated that it was closed automatically by the GitLab Alert bot. +When GitLab receives a **Recovery Alert**, it will automatically close the associated issue. This action will be recorded as a system message on the issue indicating that it was closed automatically by the GitLab Alert bot. To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. @@ -812,6 +1005,8 @@ Metric charts may also be hidden:  +You can open the link directly into your browser for a [detailed view of the data](#expand-panel). + ### Embedding metrics in issue templates It is also possible to embed either the default dashboard metrics or individual metrics in issue templates. For charts to render side-by-side, links to the entire metrics dashboard or individual metrics should be separated by either a comma or a space. @@ -907,12 +1102,20 @@ Prerequisites for embedding from a Grafana instance: 1. In the upper-left corner of the page, select a specific value for each variable required for the queries in the chart.  1. In Grafana, click on a panel's title, then click **Share** to open the panel's sharing dialog to the **Link** tab. If you click the _dashboard's_ share panel instead, GitLab will attempt to embed the first supported panel on the dashboard (if available). -1. If your Prometheus queries use Grafana's custom template variables, ensure that "Template variables" option is toggled to **On**. Of Grafana global template variables, only `$__interval`, `$__from`, and `$__to` are currently supported. Toggle **On** the "Current time range" option to specify the time range of the chart. Otherwise, the default range will be the last 8 hours. +1. If your Prometheus queries use Grafana's custom template variables, ensure that the "Template variables" option is toggled to **On**. Of Grafana global template variables, only `$__interval`, `$__from`, and `$__to` are currently supported. Toggle **On** the "Current time range" option to specify the time range of the chart. Otherwise, the default range will be the last 8 hours.  1. Click **Copy** to copy the URL to the clipboard. 1. In GitLab, paste the URL into a Markdown field and save. The chart will take a few moments to render.  +## Metrics dashboard visibility + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201924) in GitLab 13.0. + +You can set the visibility of the metrics dashboard to **Only Project Members** +or **Everyone With Access**. When set to **Everyone with Access**, the metrics +dashboard is visible to authenticated and non-authenticated users. + ## Troubleshooting When troubleshooting issues with a managed Prometheus app, it is often useful to diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 143130aebea..911493cdae9 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Monitoring AWS Resources > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index fa3590af8cf..712805b75f2 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Monitoring HAProxy > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index c2b3676b23f..6f2c2477eee 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Prometheus Metrics library > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ca1555c793b..29efe08e53d 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Monitoring Kubernetes > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index d5f078f3ddf..eda6f64ccac 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Monitoring NGINX > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 62f8c08e298..b2bc217e8bf 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Monitoring NGINX Ingress Controller > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. 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 af3b725deb6..6ba0a7610f6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Monitoring NGINX Ingress Controller with VTS metrics > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index 9df9f52ceb1..691d20e5de2 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Unit formats reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201999) in GitLab 12.9. @@ -5,19 +11,78 @@ You can select units to format your charts by adding `format` to your [axis configuration](prometheus.md#dashboard-yaml-properties). +## Internationalization and localization + +Currently, your [internationalization and localization options](https://en.wikipedia.org/wiki/Internationalization_and_localization) for number formatting are dependent on the system you are using i.e. your OS or browser. + +## Engineering Notation + +For generic or default data, numbers are formatted according to the current locale in [engineering notation](https://en.wikipedia.org/wiki/Engineering_notation). + +While an [engineering notation exists for the web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat), GitLab uses a version based off the [scientific notation](https://en.wikipedia.org/wiki/Scientific_notation). GitLab formatting acts in accordance with SI prefixes. For example, using GitLab notation, `1500.00` becomes `1.5k` instead of `1.5E3`. Keep this distinction in mind when using the engineering notation for your metrics. + +Formats: `engineering` + +SI prefixes: + +| Name | Symbol | Value | +| ---------- | ------- | -------------------------- | +| `yotta` | Y | 1000000000000000000000000 | +| `zetta` | Z | 1000000000000000000000 | +| `exa` | E | 1000000000000000000 | +| `peta` | P | 1000000000000000 | +| `tera` | T | 1000000000000 | +| `giga` | G | 1000000000 | +| `mega` | M | 1000000 | +| `kilo` | k | 1000 | +| `milli` | m | 0.001 | +| `micro` | μ | 0.000001 | +| `nano` | n | 0.000000001 | +| `pico` | p | 0.000000000001 | +| `femto` | f | 0.000000000000001 | +| `atto` | a | 0.000000000000000001 | +| `zepto` | z | 0.000000000000000000001 | +| `yocto` | y | 0.000000000000000000000001 | + +**Examples:** + +| Data | Displayed | +| --------------------------------- | --------- | +| `0.000000000000000000000008` | 8y | +| `0.000000000000000000008` | 8z | +| `0.000000000000000008` | 8a | +| `0.000000000000008` | 8f | +| `0.000000000008` | 8p | +| `0.000000008` | 8n | +| `0.000008` | 8μ | +| `0.008` | 8m | +| `10` | 10 | +| `1080` | 1.08k | +| `18000` | 18k | +| `18888` | 18.9k | +| `188888` | 189k | +| `18888888` | 18.9M | +| `1888888888` | 1.89G | +| `1888888888888` | 1.89T | +| `1888888888888888` | 1.89P | +| `1888888888888888888` | 1.89E | +| `1888888888888888888888` | 1.89Z | +| `1888888888888888888888888` | 1.89Y | +| `1888888888888888888888888888` | 1.89e+27 | + ## Numbers -For generic data, numbers are formatted according to the current locale. +For number data, numbers are formatted according to the current locale. Formats: `number` **Examples:** -| Data | Displayed | -| --------- | --------- | -| `10` | 1 | -| `1000` | 1,000 | -| `1000000` | 1,000,000 | +| Data | Displayed | +| ---------- | --------- | +| `10` | 1 | +| `1000` | 1,000 | +| `1000000` | 1,000,000 | ## Percentage diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index ba2a8f55d84..419340c14ef 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -41,7 +41,7 @@ an error message and keep troubleshooting from there. You may see an entry similar to the following in your Sidekiq log: -```text +```plaintext 2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} ``` diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md new file mode 100644 index 00000000000..a6e688887b6 --- /dev/null +++ b/doc/user/project/integrations/webex_teams.md @@ -0,0 +1,24 @@ +# Webex Teams service + +You can configure GitLab to send notifications to a Webex Teams space. + +## Create a webhook for the space + +1. Go to the [Incoming Webooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems). +1. Click **Connect** and log in to Webex Teams, if required. +1. Enter a name for the webhook and select the space that will receive the notifications. +1. Click **ADD**. +1. Copy the **Webhook URL**. + +## Configure settings in GitLab + +Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send notifications. + +1. Navigate to **Project > Settings > Integrations**. +1. Select the **Webex Teams** integration. +1. Ensure that the **Active** toggle is enabled. +1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. +1. Paste the **Webhook** URL for the Webex Teams space. +1. Configure the remaining options and then click **Test settings and save changes**. + +The Webex Teams space will begin to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 6dd2fd3b61b..89e84dda0e8 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1294,7 +1294,7 @@ X-Gitlab-Event: Job Hook } ``` -Note that `commit.id` is the id of the pipeline, not the id of the commit. +Note that `commit.id` is the ID of the pipeline, not the ID of the commit. ## Image URL rewriting diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index a72eaaa9ff1..119a53f5c35 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,8 +14,8 @@ To enable YouTrack integration in a project: | Field | Description | |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Description** | Name for the issue tracker (to differentiate between instances, for example). | - | **Project url** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues url** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues url** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | + | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | + | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | 1. Click the **Save changes** button. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 5bc71337e44..9903a711987 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -9,220 +9,271 @@ 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 provides perfect pairing between issue tracking and project management, +It pairs issue tracking and project management, keeping everything in the same place, so that you don't need to jump between different platforms to organize your workflow. -With GitLab Issue Boards, you organize your issues in lists that correspond to +With issue boards, you organize your issues in lists that correspond to their assigned labels, visualizing issues designed as cards throughout those lists. -You define your process and GitLab organizes it for you. You add your labels +You define your process, and GitLab organizes it for you. You add your labels then create the corresponding list to pull in your existing issues. When you're ready, you can drag and drop your issue cards from one step to the next. - + -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of -Issue Boards** (version introduced in GitLab 8.11 - August 2016). +the Issue Board feature (introduced in GitLab 8.11 - August 2016). -### Advanced features of Issue Boards +### Advanced features of issue boards - Create multiple issue boards per project. - Create multiple issue boards per group. **(PREMIUM)** - Add lists for [assignees](#assignee-lists-premium) and [milestones](#milestone-lists-premium). **(PREMIUM)** -Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards) -below. +Check all the [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards). - + + +--- ## How it works -The Issue Board builds on GitLab's existing +The Issue Board feature builds on GitLab's existing [issue tracking functionality](issues/index.md#issues-list) and -leverages the power of [labels](labels.md) by utilizing them as lists of the scrum board. +[labels](labels.md) by using them as lists of the Scrum board. -With the Issue Board you can have a different view of your issues while +With issue boards you can have a different view of your issues while maintaining the same filtering and sorting abilities you see across the -issue tracker. An Issue Board is based on its project's label structure, therefore, it +issue tracker. An issue board is based on its project's label structure, so it applies the same descriptive labels to indicate placement on the board, keeping consistency throughout the entire development lifecycle. -An Issue Board shows you what issues your team is working on, who is assigned to each, +An issue board shows you what issues your team is working on, who is assigned to each, and where in the workflow those issues are. You create issues, host code, perform reviews, build, test, -and deploy from one single platform. Issue Boards help you to visualize -and manage the entire process _in_ GitLab. +and deploy from one single platform. Issue boards help you to visualize +and manage the entire process in GitLab. -With [Multiple Issue Boards](#use-cases-for-multiple-issue-boards), +With [multiple issue boards](#use-cases-for-multiple-issue-boards), you go even further, as you can not only keep yourself and your project -organized from a broader perspective with one Issue Board per project, +organized from a broader perspective with one issue board per project, but also allow your team members to organize their own workflow by creating -multiple Issue Boards within the same project. +multiple issue boards within the same project. ## Use cases -There are many ways to use GitLab Issue Boards tailored to your own preferred workflow. -Here are some common use cases for Issue Boards. +There are many ways to use GitLab issue boards tailored to your own preferred workflow. +Here are some common use cases for issue boards. -### Use cases for a single Issue Board +### Use cases for a single issue board -GitLab Workflow allows you to 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, categorize them +with labels, and from there, organize and prioritize them with issue boards. For example, let's consider this simplified development workflow: -1. You have a repository hosting your app's codebase - and your team actively contributing to code -1. Your **backend** team starts working a new - implementation, gathers feedback and approval, and pass it over to **frontend** -1. When frontend is complete, the new feature is deployed to **staging** to be tested -1. When successful, it is deployed to **production** +1. You have a repository that hosts your application's codebase, and your team actively contributes code. +1. Your **backend** team starts working on a new implementation, gathers feedback and approval, and + passes it over to the **frontend** team. +1. When frontend is complete, the new feature is deployed to a **staging** environment to be tested. +1. When successful, it's deployed to **production**. -If we have the labels "**backend**", "**frontend**", "**staging**", and -"**production**", and an Issue Board with a list for each, we can: +If you have the labels "**backend**", "**frontend**", "**staging**", and +"**production**", and an issue board with a list for each, you can: -- Visualize the entire flow of implementations since the - beginning of the development life cycle until deployed to production -- Prioritize the issues in a list by moving them vertically -- Move issues between lists to organize them according to the labels you've set -- Add multiple issues to lists in the board by selecting one or more existing issues +- Visualize the entire flow of implementations since the beginning of the development life cycle + until deployed to production. +- Prioritize the issues in a list by moving them vertically. +- Move issues between lists to organize them according to the labels you've set. +- Add multiple issues to lists in the board by selecting one or more existing issues.  -### Use cases for Multiple Issue Boards +--- + +### Use cases for multiple issue boards -With [Multiple Issue Boards](#multiple-issue-boards), +With [multiple issue boards](#multiple-issue-boards), each team can have their own board to organize their workflow individually. #### Scrum team -With Multiple Issue Boards, each team has one board. Now you can move issues through each +With multiple issue boards, each team has one board. Now you can move issues through each part of the process. For instance: **To Do**, **Doing**, and **Done**. #### Organization of topics -Create lists to order things by topic and quickly change them between topics or groups, -such as between **UX**, **Frontend**, and **Backend**. The changes will be reflected across boards, -as changing lists will update the label accordingly. +Create lists to order issues by topic and quickly change them between topics or groups, +such as between **UX**, **Frontend**, and **Backend**. The changes are reflected across boards, +as changing lists updates the labels on each issue accordingly. #### Advanced team handover -For example, suppose we have a UX team with an Issue Board that contains: +For example, suppose we have a UX team with an issue board that contains: - **To Do** - **Doing** - **Frontend** -When done with something, they move the card to **Frontend**. The Frontend team's board looks like: +When finished with something, they move the card to **Frontend**. The Frontend team's board looks like: - **Frontend** - **Doing** - **Done** -Cards finished by the UX team will automatically appear in the **Frontend** column when they're ready for them. +Cards finished by the UX team automatically appear in the **Frontend** column when they are ready +for them. NOTE: **Note:** For a broader use case, please see the blog post [GitLab Workflow, an Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). For a real use case example, you can read why -[Codepen decided to adopt Issue Boards](https://about.gitlab.com/blog/2017/01/27/codepen-welcome-to-gitlab/#project-management-everything-in-one-place) +[Codepen decided to adopt issue boards](https://about.gitlab.com/blog/2017/01/27/codepen-welcome-to-gitlab/#project-management-everything-in-one-place) to improve their workflow with multiple boards. #### Quick assignments -Create lists for each of your team members and quickly drag-and-drop issues onto each team member. +Create lists for each of your team members and quickly drag and drop issues onto each team member's +list. + +## Issue board terminology + +An **issue board** represents a unique view of your issues. It can have multiple lists with each +list consisting of issues represented by cards. + +A **list** is a column on the issue board that displays issues matching certain attributes. +In addition to the default "Open" and "Closed" lists, each additional list shows issues matching +your chosen label, assignee, or milestone. On the top of each list you can see the number of issues +that belong to it. Types of lists include: + +- **Open** (default): all open issues that do not belong to one of the other lists. + Always appears as the leftmost list. +- **Closed** (default): all closed issues. Always appears as the rightmost list. +- **Label list**: all open issues for a label. +- [**Assignee list**](#assignee-lists-premium): all open issues assigned to a user. +- [**Milestone list**](#milestone-lists-premium): all open issues for a milestone. -## Issue Board terminology +A **Card** is a box on a list, and it represents an issue. You can drag cards from one list to +another to change their label, assignee, or milestone. The information you can see on a +card includes: -- **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards. -- **List** - A column on the issue board that displays issues matching certain attributes. In addition to the default lists of 'Open' and 'Closed' issue, each additional list will show issues matching your chosen label or assignee. On the top of that list you can see the number of issues that belong to it. - - **Label list**: a list based on a label. It shows all opened issues with that label. - - **Assignee list**: a list which includes all issues assigned to a user. - - **Open** (default): shows all open issues that do not belong to one of the other lists. Always appears as the leftmost list. - - **Closed** (default): shows all closed issues. Always appears as the rightmost list. -- **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list. +- Issue title +- Associated labels +- Issue number +- Assignee ## Permissions -[Reporters and up](../permissions.md) can use all the functionality of the -Issue Board to create or delete lists, and drag issues from one list to another. +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. -## GitLab Enterprise features for Issue Boards +## GitLab Enterprise features for issue boards -GitLab Issue Boards are available on GitLab Core and GitLab.com Free, but some -advanced functionalities are only present in higher tiers: GitLab.com Bronze, -Silver, or Gold, or GitLab self-managed Starter, Premium, and Ultimate, as described -in the following sections. +GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some +advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -For a collection of [features per tier](#summary-of-features-per-tier), check the summary below. +### Summary of features per tier + +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: -### Multiple Issue Boards +| Tier | Number of Project issue boards | Number of Group issue boards | Configurable issue boards | Assignee lists | +|------------------|--------------------------------|------------------------------|---------------------------|----------------| +| Core / Free | Multiple | 1 | No | No | +| Starter / Bronze | Multiple | 1 | Yes | No | +| Premium / Silver | Multiple | Multiple | Yes | Yes | +| Ultimate / Gold | Multiple | Multiple | Yes | Yes | -> - Multiple Issue Boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. -> - Multiple Issue Boards per group is available in [GitLab Premium Edition](https://about.gitlab.com/pricing/). +### Multiple issue boards -Multiple Issue Boards, as the name suggests, 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. +> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. +> - Multiple issue boards per 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. -Clicking on the current board name in the upper left corner will reveal a -menu from where you can create another Issue Board or delete the existing one. Using the search box at the top of the menu, you can filter the listed boards. -When you have 10 or more boards available, a "Recent" section is also shown in the menu. -These are shortcuts to your last 4 visited boards. +When you have ten or more boards available, a **Recent** section is also shown in the menu, with +shortcuts to your last four visited boards. - + When you're revisiting an issue board in a project or group with multiple boards, -GitLab will automatically load the last board you visited. +GitLab automatically loads the last board you visited. + +#### Create an issue board -### Configurable Issue Boards **(STARTER)** +To create a new issue board: -> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration). +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Create new board**. +1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. -An Issue Board can be associated with a GitLab [Milestone](milestones/index.md#milestones), +#### Delete an issue board + +To delete the currently active issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Delete board**. +1. Click **Delete** to confirm. + +### Configurable issue boards **(STARTER)** + +> [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. + +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. 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 on the "Edit board" button. -Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to +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 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. +(for example, milestone, assignee, or weight) from the issue board.  -If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope". +If you don't have editing permission in a board, you're still able to see the configuration by +clicking **View scope**.  +--- + ### Focus mode -> - Introduced in [GitLab Starter 9.1](https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep). -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 12.10. +> - [Introduced]((https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep)) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab.com in 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 13.0. -Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. +Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI +is hidden, allowing you to focus on issues in the board.  -### Sum of Issue Weights **(STARTER)** +--- + +### Sum of issue weights **(STARTER)** The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, especially in combination with [assignee lists](#assignee-lists-premium). - + + +--- -### Group Issue Boards **(PREMIUM)** +### Group issue boards **(PREMIUM)** -> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#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 @@ -231,102 +282,114 @@ boards. When updating milestones and labels for an issue through the sidebar upd group-level objects are available. NOTE: **Note:** -Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) and -one group issue board per group was made available in GitLab 10.6 Core. +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 11.0 Premium. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. -Like a regular list that shows all issues that have the list label, you can add -an assignee list that shows all issues assigned to the given user. +Like in a regular list that shows all issues with a chosen label, you can add +an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists. To add an assignee list: 1. Click **Add list**. 1. Select the **Assignee list** tab. -1. Search and click on the user you want to add as an assignee. +1. Search and click the user you want to add as an assignee. Now that the assignee list is added, you can assign or unassign issues to that user -by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list. +by [dragging issues](#drag-issues-between-lists) to and from an assignee list. To remove an assignee list, just as with a label list, click the trash icon.  +--- + ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6469) in GitLab 11.2 Premium. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. -As of 11.2, you're also able to create lists of a milestone. As the name states, -these are lists that filter issues by the assigned milestone, giving you more -freedom and visibility on the Issue Board. To do so: +You're also able to create lists of a milestone. These are lists that filter issues by the assigned +milestone, giving you more freedom and visibility on the issue board. To add a milestone list: 1. Click **Add list**. 1. Select the **Milestone** tab. -1. Search and click on the milestone. +1. Search and click the milestone. -Similar to the assignee lists, you're now able to [drag issues](#dragging-issues-between-lists) -to and/or from a milestone list to manipulate the milestone of the dragged issues. -As on another list types, click on the trash icon to remove it. +Similar to the assignee lists, you're now 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.  +--- + ## Work In Progress limits **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11403) in GitLab 12.7 -You can set Work In Progress (WIP) limits per issues list. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. For example, for a list with 4 issues, and a limit of 5, the header will show `4/5`. If you exceed the limit, the current number of issues is shown in red. For example, you have a list with 5 issues with a limit of 5. When you move another issue to that list, the list's header displays `6/5`, with the `6` shown in red. +You can set Work In Progress (WIP) limits per issues list. When a limit is set, the list's header +shows the number of issues in the list and the soft limit of issues. -To set a WIP limit for a list: +Examples: -1. Navigate to a Project or Group board for which you have membership and click on the Settings icon (gear) in a list's header. -1. Next to **Work In Progress Limit**, click **Edit** and enter the maximum number of issues. Press `Enter` to save. +- You have a list with four issues, and a limit of five, the header will show **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. -### Summary of features per tier - -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: +To set a WIP limit for a list: -| Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists | -|----------|--------------------------------|------------------------------|---------------------------|----------------| -| Core / Free | Multiple | 1 | No | No | -| Starter / Bronze | Multiple | 1 | Yes | No | -| Premium / Silver | Multiple | Multiple | Yes | Yes | -| Ultimate / Gold | Multiple | Multiple | Yes | Yes | +1. Navigate to a Project or Group board of which you're a member. +1. Click the Settings icon (**{settings}**) in a list's header. +1. Next to **Work In Progress Limit**, click **Edit**. +1. Enter the maximum number of issues. +1. Press <kbd>Enter</kbd> to save. ## Blocked issues > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34723) in GitLab 12.8. -If an issue is blocked by another issue, an icon will display next to its title to differentiate it from unblocked issues. +If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked +status.  -## Actions you can take on an Issue Board +--- + +## Actions you can take on an issue board + +- [Create a new list](#create-a-new-list). +- [Delete an existing list](#delete-a-list). +- [Add issues to a list](#add-issues-to-a-list). +- [Remove an issue from a list](#remove-an-issue-from-a-list). +- [Filter issues](#filter-issues) that appear across your issue board. +- [Create workflows](#create-workflows). +- [Drag issues between lists](#drag-issues-between-lists). +- [Mulit-select issue cards](#multi-select-issue-cards). +- [Re-order issues in lists](#issue-ordering-in-a-list). +- Drag and reorder the lists. +- Change issue labels (by dragging an issue between lists). +- Close an issue (by dragging it to the **Done** list). -- [Create a new list](#creating-a-new-list). -- [Delete an existing list](#deleting-a-list). -- Drag issues between lists. -- Re-order issues in lists. -- Drag and reorder the lists themselves. -- Change issue labels on-the-fly while dragging issues between lists. -- Close an issue if you drag it to the **Done** list. -- Create a new list from a non-existing label by [creating the label on-the-fly](#creating-a-new-list) - within the Issue Board. -- [Filter issues](#filtering-issues) that appear across your Issue Board. +If you're not able to do some of the things above, make sure you have the right +[permissions](#permissions). -If you are not able to perform one or more of the things above, make sure you -have the right [permissions](#permissions). +### First time using an issue board -### First time using the 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 first time you navigate to your Issue Board, you will be presented with -a default list (**Done**) and a welcoming message that gives -you two options. You can either create a predefined set of labels and create -their corresponding lists to the Issue Board or opt-out and use your own lists. +- 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. - + 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, @@ -334,99 +397,74 @@ 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. -### Creating a new list +### Create a new list -Create a new list by clicking on the **Add list** button at the upper -right corner of the Issue Board. +Create a new list by clicking the **Add list** button in the upper right corner of the issue board. - + -Simply 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 will be inserted at the end of the lists, before **Done**. Moving and reordering lists is as easy as dragging them around. -To create a list for a label that doesn't yet exist, simply create the label by -choosing **Create new label**. The label will be created on-the-fly and it will -be immediately added to the dropdown. You can now choose it to create a list. +To create a list for a label that doesn't yet exist, create the label by +choosing **Create new label**. This creates the label immediately and adds it to the dropdown. +You can now choose it to create a list. -### Deleting a list +### Delete a list -To delete a list from the Issue Board use the small trash icon that is present +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. 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. -### Adding issues to a list +### Add issues to a list -You can add issues to a list by clicking the **Add issues** button that is -present in the upper right corner of the Issue Board. This will open up a modal +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 window where you can see all the issues that do not belong to any list. -Select one or more issues by clicking on the cards and then click **Add issues** +Select one or more issues by clicking the cards and then click **Add issues** to add them to the selected list. You can limit the issues you want to add to the list by filtering by author, assignee, milestone, and label.  -### Removing an issue from a list - -Removing an issue from a list can be done by clicking on the issue card and then -clicking the **Remove from board** button in the sidebar. Under the hood, the -respective label is removed, and as such it's also removed from the list and the -board itself. - - - -### Issue ordering in a list +--- -When visiting a board, issues appear ordered in any list. You are able to change -that order simply by dragging and dropping the issues. The changed order will be saved -to the system so that anybody who visits the same board later will see the reordering, -with some exceptions. +### Remove an issue from a list -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 with -respect to other issues in that list according to [Priority order](labels.md#label-priority). +Removing an issue from a list can be done by clicking the issue card and then +clicking the **Remove from board** button in the sidebar. The +respective label is removed. -At that 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 drag-and-drop reorder that 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 drag-and-drop reordered 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. + -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, -and vice versa. +--- -### Filtering issues +### Filter issues -You should be able to use the filters on top of your Issue Board to show only +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 -since the metadata from the issues and labels are re-used in the Issue Board. +since the metadata from the issues and labels are re-used in the issue board. You can filter by author, assignee, milestone, and label. -### Creating workflows +### Create workflows -By reordering your lists, you can create workflows. As lists in Issue Boards are +By reordering your lists, you can create workflows. As lists in issue boards are based on labels, it works out of the box with your existing issues. So if you've already labeled things with 'Backend' and 'Frontend', the issue appears in the lists as you create them. In addition, this means you can easily move something between lists by changing a label. -A typical workflow of using the Issue Board would be: +A typical workflow of using an issue board would be: 1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority) labels so that you can easily categorize your issues. 1. You have a bunch of issues (ideally labeled). -1. You visit the Issue Board and start [creating lists](#creating-a-new-list) to +1. You visit the issue board and start [creating lists](#create-a-new-list) to create a workflow. 1. You move issues around in lists so that your team knows who should be working on what issue. @@ -446,9 +484,11 @@ issue. This process can be seen clearly when visiting an issue since with every move to another list the label changes and a system not is recorded. - + -### Dragging issues between lists +--- + +### Drag issues between lists When dragging issues between lists, different behavior occurs depending on the source list and the target list. @@ -472,6 +512,35 @@ To select and move multiple cards:  +--- + +### Issue ordering in a list + +When visiting a board, issues appear ordered in any list. You're able to change +that order by dragging and dropping the issues. The changed order will be saved +to the system so that anybody who visits the same board later will see 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 with +respect to other issues in that list according to [Priority order](labels.md#label-priority). + +At that 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 drag-and-drop reorder that 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 drag-and-drop reordered 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. + +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, +and vice versa. + ## Tips A few things to remember: @@ -480,8 +549,8 @@ A few things to remember: and adds the label from the list it goes to. - An issue can exist in multiple lists if it has more than one label. - Lists are populated with issues automatically if the issues are labeled. -- Clicking on the issue title inside a card takes you to that issue. -- Clicking on a label inside a card quickly filters the entire Issue Board +- Clicking the issue title inside a card takes you to that issue. +- Clicking a label inside a card quickly filters the entire issue board and show only the issues from all lists that have that label. - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index ec53b3dbbba..af01534a67f 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -70,7 +70,7 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot | Labels | Title of any labels joined with a `,` | | Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | | Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| Epic ID | Id of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | | Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | ## Limitations diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 1078d0410ed..64f56221632 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,6 +1,7 @@ -# Design Management **(PREMIUM)** +# Design Management -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. CAUTION: **Warning:** This an **alpha** feature and is subject to change at any time without @@ -86,6 +87,7 @@ Copy-and-pasting has some limitations: - You can paste only one image at a time. When copy/pasting multiple files, only the first one will be uploaded. - All images will be converted to `png` format under the hood, so when you want to copy/paste `gif` file, it will result in broken animation. +- If you are pasting a screenshot from the clipboard, it will be renamed to `design_<timestamp>.png` - Copy/pasting designs is not supported on Internet Explorer. Designs with the same filename as an existing uploaded design will create a new version diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index f70597f6875..0be0cdd11bd 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -24,6 +24,11 @@ Changes are saved immediately.  +The last way to set a due date is by using [quick actions](../quick_actions.md), directly in an issue's description or comment: + +- `/due <date>`: set due date. Examples of valid `<date>` include `in 2 days`, `this Friday`, and `December 31st`. +- `/remove_due_date`: remove due date. + ## Making use of due dates Issues that have a due date can be easily seen in the issue tracker, diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 0f9295e1afd..22221531360 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -28,6 +28,11 @@ you can also view all the issues collectively at the group level. See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +To learn how GitLab's Strategic Marketing department uses GitLab issues with [labels](../labels.md) and +[issue boards](../issue_board.md), see the video on +[Managing Commitments with Issues](https://www.youtube.com/watch?v=cuIHNintg1o&t=3). + ## Parts of an issue Issues contain a variety of content and metadata, enabling a large range of flexibility diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 4ee29f3357d..4e329889e7c 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -50,7 +50,7 @@ create issues for the same project.  -### New issue via Service Desk **(PREMIUM)** +### New issue via Service Desk **(STARTER)** Enable [Service Desk](../service_desk.md) for your project and offer email support. By doing so, when your customer sends a new email, a new issue can be created in @@ -92,9 +92,17 @@ field values using query string parameters in a URL. This is useful for embeddin a URL in an external HTML page, and also certain scenarios where you want the user to create an issue with certain fields prefilled. -The title, description, and description template fields can be prefilled using -this method. You cannot pre-fill both the description and description template fields -in the same URL (since a description template also populates the description field). +The title, description, description template, and confidential fields can be prefilled +using this method. You cannot pre-fill both the description and description template +fields in the same URL (since a description template also populates the description +field). + +| Field | URL Parameter Name | Notes | +|----------------------|-----------------------|-------------------------------------------------------| +| title | `issue[title]` | | +| description | `issue[description]` | | +| description template | `issuable_template` | | +| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential | Follow these examples to form your new issue URL with prefilled fields. @@ -102,6 +110,8 @@ Follow these examples to form your new issue URL with prefilled fields. and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` - For a new issue in the GitLab Community Edition project with a pre-filled title and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` +- For a new issue in the GitLab Community Edition project with a pre-filled title, + a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` ## Moving Issues @@ -117,7 +127,10 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. -To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](../../../raketasks/backup_restore.md#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console. +To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below +script. Please be sure to change **project**, **admin_user** and **target_project** to your values. +We do also recommend [creating a backup](../../../raketasks/backup_restore.md#back-up-gitlab) before +attempting any changes in the console. ```ruby project = Project.find_by_full_path('full path of the project where issues are moved from') @@ -170,7 +183,7 @@ but it will not close automatically. If the issue is in a different repository than the MR, add the full URL for the issue(s): -```md +```markdown Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> ``` @@ -179,7 +192,7 @@ Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> When not specified, the default issue closing pattern as shown below will be used: ```shell -((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) +\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) ``` This translates to the following keywords: diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 5fba73c2971..8002b528a80 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -10,12 +10,14 @@ The relationship only shows up in the UI if the user can see both issues. ## 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) 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. + You can relate one issue to another by clicking the related issues "+" button in the header of the related issue block. Then, input the issue reference number or paste in the full URL of the issue. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2035) in GitLab 12.8. - Additionally, you can select whether the current issue relates to, blocks, or is blocked by the issues being entered.  diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 9cf50d3aaed..f3b59147d5b 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -2,13 +2,18 @@ ## Overview -Labels allow you to categorize epics, issues, and merge requests using descriptive titles like -`bug`, `feature request`, or `docs`, as well as customizable colors. They allow you to quickly -and dynamically filter and manage epics, issues, and merge requests, and are a key -part of [issue boards](issue_board.md). +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 +so you can track and find the work items you're interested in. -You can use labels to help [search](../search/index.md#issues-and-merge-requests) in -lists of issues, merge requests, and epics, as well as [search in issue boards](../search/index.md#issue-boards). +Labels are a key part of [issue boards](issue_board.md). With labels you can: + +- Categorize epics, issues, and merge requests using colors and descriptive titles like +`bug`, `feature request`, or `docs`. +- Dynamically filter and manage epics, issues, and merge requests. +- [Search lists of issues, merge requests, and epics](../search/index.md#issues-and-merge-requests), + as well as [issue boards](../search/index.md#issue-boards). ## Project labels and group labels @@ -164,7 +169,7 @@ Suppose you have the labels `workflow::development`, `workflow::review`, and applied, and a developer wanted to advance the issue to `workflow::review`, they would simply apply that label, and the `workflow::development` label would automatically be removed. This behavior already exists when you move issues -across label lists in an [issue board](issue_board.md#creating-workflows), but +across label lists in an [issue board](issue_board.md#create-workflows), but now, team members who may not be working in an issue board directly would still be able to advance workflow states consistently in issues themselves. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 27a5701e6c2..9020dc335b6 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,4 +1,4 @@ -# Project's members +# Members of a project You can manage the groups and users and their access levels in all of your projects. You can also personalize the access level you give each user, diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 755bf0447e3..427761281f6 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -18,6 +18,23 @@ measuring the accessibility of web sites, and has built a simple This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. +## Accessibility Merge Request widget + +[Since GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/39425), in addition to the report artifact that is created, GitLab will also show the +Accessibility Report in the merge request widget area: + + + +This widget comes with the `:accessibility_report_view` feature flag disabled by default while we test feature stability. +Once we have determined the widget is stable, this feature will be enabled by default. + +To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the +following command: + +```ruby +Feature.enable(:accessibility_report_view) +``` + ## Configure Accessibility Testing This example shows how to run [pa11y](https://pa11y.org/) @@ -46,10 +63,13 @@ Pa11y against the webpages defined in `a11y_urls`, and builds an HTML report for 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). -A single `accessibility.json` artifact is created and saved along with the individual HTML reports. +A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned. NOTE: **Note:** +For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). + +NOTE: **Note:** For GitLab versions earlier than 12.9, you can use `include:remote` and use a link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 1bca5d2a212..0fa3d7be265 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -6,55 +6,50 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. -If your application offers a web interface and you are using +If your application offers a web interface and you're using [GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance impact of pending code changes. ## Overview GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source -tool for measuring the performance of web sites, and has built a simple -[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance) -which outputs the results in a file called `performance.json`. This plugin -outputs the performance score for each page that is analyzed. - +tool, for measuring the performance of web sites. GitLab has built a simple +[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance) which outputs +the performance score for each page analyzed in a file called `performance.json`. The [Sitespeed.io performance score](https://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html) -is a composite value based on best practices, and we will be expanding support -for [additional metrics](https://gitlab.com/gitlab-org/gitlab/issues/4370) -in a future release. +is a composite value based on best practices. -Going a step further, GitLab can show the Performance report right -in the merge request widget area (see below). +GitLab can [show the Performance report](#how-browser-performance-testing-works) +in the merge request widget area. ## Use cases -For instance, consider the following workflow: +Consider the following workflow: 1. A member of the marketing team is attempting to track engagement by adding a new tool. 1. With browser performance metrics, they see how their changes are impacting the usability of the page for end users. -1. The metrics show that after their changes the performance score of the page has gone down. -1. When looking at the detailed report, they see that the new JavaScript library was - included in `<head>` which affects loading page speed. -1. They ask a front end developer to help them, who sets the library to load asynchronously. -1. The frontend developer approves the merge request and authorizes its deployment to production. - -## How it works +1. The metrics show that after their changes, the performance score of the page has gone down. +1. When looking at the detailed report, they see the new JavaScript library was + included in `<head>`, which affects loading page speed. +1. They ask for help from a front end developer, who sets the library to load asynchronously. +1. The frontend developer approves the merge request, and authorizes its deployment to production. -First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the -[Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium). -For more information on how the Performance job should look like, check the -example on [Configuring Browser Performance Testing](#configuring-browser-performance-testing). +## How browser performance testing works +First, define a job in your `.gitlab-ci.yml` file that generates the +[Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium). GitLab then checks this report, compares key performance metrics for each page -between the source and target branches, and shows the information right on the merge request. +between the source and target branches, and shows the information in the merge request. + +For an example Performance job, see +[Configuring Browser Performance Testing](#configuring-browser-performance-testing). NOTE: **Note:** -If the Performance report doesn't have anything to compare to, no information -will be displayed in the merge request area. That is the case when you add the -Performance job in your `.gitlab-ci.yml` for the very first time. -Consecutive merge requests will have something to compare to, and the Performance -report will be shown properly. +If the Performance report has no data to compare, such as when you add the +Performance job in your `.gitlab-ci.yml` for the very first time, no information +displays in the merge request widget area. Consecutive merge requests will have data for +comparison, and the Performance report will be shown properly.  @@ -64,52 +59,51 @@ This example shows how to run the [sitespeed.io container](https://hub.docker.co on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. -First, you need GitLab Runner with -[docker-in-docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). +1. First, set up GitLab Runner with a + [docker-in-docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). +1. After configuring the Runner, add a new job to `.gitlab-ci.yml` that generates + the expected report. +1. Define the `performance` job according to your version of GitLab: -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that generates the -expected report. + - For GitLab 12.4 and later - [include](../../../ci/yaml/README.md#includetemplate) the + [`Browser-Performance.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml) provided as a part of your GitLab installation. + - For GitLab versions earlier than 12.4 - Copy and use the job as defined in the + [`Browser-Performance.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). -For GitLab 12.4 and later, to define the `performance` job, you must -[include](../../../ci/yaml/README.md#includetemplate) the -[`Browser-Performance.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml) -that's provided as a part of your GitLab installation. -For GitLab versions earlier than 12.4, you can copy and use the job as defined -in that template. + CAUTION: **Caution:** + The job definition provided by the template does not support Kubernetes yet. + For a complete example of a more complex setup that works in Kubernetes, see + [`Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml). -CAUTION: **Caution:** -The job definition provided by the template does not support Kubernetes yet. For a complete example of a more complex setup -that works in Kubernetes, see [here](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml). +1. Add the following to your `.gitlab-ci.yml` file: -Add the following to your `.gitlab-ci.yml` file: + ```yaml + include: + template: Verify/Browser-Performance.gitlab-ci.yml -```yaml -include: - template: Verify/Browser-Performance.gitlab-ci.yml + performance: + variables: + URL: https://example.com + ``` -performance: - variables: - URL: https://example.com -``` - -CAUTION: **Caution:** -The job definition provided by the template is supported in GitLab 11.5 and later versions. -It also requires GitLab Runner 11.5 or later. For earlier versions, use the -[previous job definitions](#previous-job-definitions). + CAUTION: **Caution:** + The job definition provided by the template is supported in GitLab 11.5 and later versions. + It also requires GitLab Runner 11.5 or later. For earlier versions, use the + [previous job definitions](#previous-job-definitions). -The above example will create a `performance` job in your CI/CD pipeline and will run +The above example creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. The [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance) -is downloaded in order to save the report as a [Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium) -that you can later download and analyze. Due to implementation limitations we always +is downloaded to save the report as a [Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium) +that you can later download and analyze. Due to implementation limitations, we always take the latest Performance artifact available. -The full HTML sitespeed.io report will also be saved as an artifact, and if you have -[GitLab Pages](../pages/index.md) enabled, it can be viewed directly in your browser. +The full HTML sitespeed.io report is saved as an artifact, and if +[GitLab Pages](../pages/index.md) is enabled, it can be viewed directly in your browser. -It is also possible to customize options by setting the `SITESPEED_OPTIONS` variable. -For example, this is how to override the number of runs sitespeed.io -will make on the given URL: +You can also customize options by setting the `SITESPEED_OPTIONS` variable. +For example, you can override the number of runs sitespeed.io +makes on the given URL: ```yaml include: @@ -122,27 +116,47 @@ performance: ``` For further customization options for sitespeed.io, including the ability to provide a -list of URLs to test, please see the [Sitespeed.io Configuration](https://www.sitespeed.io/documentation/sitespeed.io/configuration/) +list of URLs to test, please see the +[Sitespeed.io Configuration](https://www.sitespeed.io/documentation/sitespeed.io/configuration/) documentation. TIP: **Tip:** Key metrics are automatically extracted and shown in the merge request widget. +### Configuring degradation threshold + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27599) in GitLab 13.0. + +You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. +This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up +if the `Total Score` metric degrades by 5 points or more: + +```yaml +include: + template: Verify/Browser-Performance.gitlab-ci.yml + +performance: + variables: + URL: https://example.com + DEGRADATION_THRESHOLD: 5 +``` + +The `Total Score` metric is based on sitespeed.io's [coach performance score](https://www.sitespeed.io/documentation/sitespeed.io/metrics/#performance-score). There is more information in [the coach documentation](https://www.sitespeed.io/documentation/coach/how-to/#what-do-the-coach-do). + ### Performance testing on Review Apps -The above CI YML is great for testing against static environments, and it can -be extended for dynamic environments. There are a few extra steps to take to -set this up: +The above CI YAML configuration is great for testing against static environments, and it can +be extended for dynamic environments, but a few extra steps are required: 1. The `performance` job should run after the dynamic environment has started. 1. In the `review` job, persist the hostname and upload it as an artifact so - it's available to the `performance` job (the same can be done for static - environments like staging and production to unify the code path). Saving it - as an artifact is as simple as `echo $CI_ENVIRONMENT_URL > environment_url.txt` + it's available to the `performance` job. The same can be done for static + environments like staging and production to unify the code path. You can save it + as an artifact with `echo $CI_ENVIRONMENT_URL > environment_url.txt` in your job's `script`. 1. In the `performance` job, read the previous artifact into an environment - variable, in this case `$URL` because this is what our sitespeed.io command - uses for the URL parameter. Because Review App URLs are dynamic, we define + variable. In this case, use `$URL` because the sitespeed.io command + uses it for the URL parameter. Because Review App URLs are dynamic, define the `URL` variable through `before_script` instead of `variables`. 1. You can now run the sitespeed.io container against the desired hostname and paths. @@ -183,11 +197,11 @@ performance: ### Previous job definitions CAUTION: **Caution:** -Before GitLab 11.5, Performance job and artifact had to be named specifically +Before GitLab 11.5, the Performance job and artifact had to be named specifically to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained they have been deprecated +While these old job definitions are still maintained, they have been deprecated and may be removed in next major release, GitLab 12.0. -You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. +GitLab recommends you update your current `.gitlab-ci.yml` configuration to reflect that change. For GitLab 11.4 and earlier, the job should look like: diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index a7e712a4c0a..beb90e30906 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -27,7 +27,19 @@ in the merge request widget area:  -For more information, see the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). +Watch a quick walkthrough of Code Quality in action: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=B32LxtJKo9M">Code Quality: Speed Run</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/B32LxtJKo9M" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +NOTE: **Note:** +For one customer, the auditor found that having Code Quality, SAST, and Container Scanning all automated in GitLab CI/CD was almost better than a manual review! [Read more](https://about.gitlab.com/customers/bi_worldwide/). + +See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). ## Use cases @@ -37,7 +49,7 @@ For instance, consider the following workflow: feature in your app faster. 1. With Code Quality reports, they analyze how their implementation is impacting the code quality. -1. The metrics show that their code degrade the quality in 10 points. +1. The metrics show that their code degrades the quality by 10 points. 1. You ask a co-worker to help them with this modification. 1. They both work on the changes until Code Quality report displays no degradations, only improvements. @@ -53,10 +65,10 @@ also requires the GitLab Runner 11.5 or later. For earlier versions, use the This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. -First, you need GitLab Runner with: +First, you need GitLab Runner configured: -- The [docker-in-docker executor](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). -- Enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. +- For the [docker-in-docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). +- With enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. Once you set up the Runner, include the CodeQuality template in your CI config: @@ -67,7 +79,7 @@ include: The above example will create a `code_quality` job in your CI/CD pipeline which will scan your source code for code quality issues. The report will be saved as a -[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter) +[Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter) that you can later download and analyze. Due to implementation limitations we always take the latest Code Quality artifact available. @@ -227,7 +239,7 @@ do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the [Code Quality report - artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter). + artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality-starter). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index d8a2b427288..544727380e7 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -171,7 +171,7 @@ When the changes are merged, your changes are added to the upstream repository a the branch as per specification. After your work is merged, if you don't intend to make any other contributions to the upstream project, you can unlink your fork from its upstream project in the **Settings > Advanced Settings** section by -[removing the forking relashionship](../settings/index.md#removing-a-fork-relationship). +[removing the forking relationship](../settings/index.md#removing-a-fork-relationship). For further details, [see the forking workflow documentation](../repository/forking_workflow.md). diff --git a/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png b/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png Binary files differnew file mode 100644 index 00000000000..c52bf9964f1 --- /dev/null +++ b/doc/user/project/merge_requests/img/accessibility_mr_widget_v13_0.png diff --git a/doc/user/project/merge_requests/img/code_quality.png b/doc/user/project/merge_requests/img/code_quality.png Binary files differindex a20f6476fb8..3c6c92baad2 100644 --- a/doc/user/project/merge_requests/img/code_quality.png +++ b/doc/user/project/merge_requests/img/code_quality.png 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 bb5aadfa9b9..fdcb1049ef7 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 @@ -64,6 +64,15 @@ list.  +### Merge requests commit navigation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To seamlessly navigate among commits in a merge request, from the **Commits** tab, click one of +the commits to open the single-commit view. From there, you can navigate among the commits +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. @@ -102,7 +111,7 @@ you will be able to see: - Both pre and post-merge pipelines and the environment information if any. - Which deployments are in progress. -If there's an [environment](../../../ci/environments.md) and the application is +If there's an [environment](../../../ci/environments/index.md) and the application is successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 71fbdaf112f..84d60fca72d 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -17,14 +17,14 @@ MR is merged. ## How test coverage visualization works Collecting the coverage information is done via GitLab CI/CD's -[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). +[artifacts reports feature](../../../ci/pipelines/job_artifacts.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab will then take the coverage information in all the files and combine it together. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/README.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/pipelines/job_artifacts.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 2f51af24a95..84934148bdc 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -57,7 +57,7 @@ source and target branch can be shown mixed together making it hard to understand which changes are being added and which already exist in the target branch. -In GitLab 12.10, we added an **experimental** comparison mode, which +In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down @@ -67,26 +67,6 @@ current default comparison.  -### Enable or disable `HEAD` comparison mode **(CORE ONLY)** - -`HEAD` comparison mode 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/troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session) -can enable it for your instance. You're welcome to test it, but use it at your -own risk. - -To enable it: - -```ruby -Feature.enable(:diff_compare_with_head) -``` - -To disable it: - -```ruby -Feature.disable(:diff_compare_with_head) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index c5ab8d66852..120c7a35cb2 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -229,5 +229,5 @@ 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-foss/issues/29566) +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. diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md new file mode 100644 index 00000000000..2dcf72aaf01 --- /dev/null +++ b/doc/user/project/operations/alert_management.md @@ -0,0 +1,79 @@ +# Alert Management + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. + +Alert Management enables developers to easily discover and view the alerts +generated by their application. By surfacing alert information where the code is +being developed, efficiency and awareness can be increased. + +## Enable Alert Management + +NOTE: **Note:** +You will need at least Maintainer [permissions](../../permissions.md) to enable the Alert Management feature. + +1. Follow the [instructions for toggling generic alerts](../integrations/generic_alerts.md#setting-up-generic-alerts) +1. You can now visit **{cloud-gear}** **Operations > Alerts** in your project's sidebar to [view a list](#alert-management-list) of alerts. + + + +## Populate Alert data + +To populate data, see the instructions for +[customizing the payload](../integrations/generic_alerts.md) and making a +request to the alerts endpoint. + +## Alert Management severity + +Each level of alert contains a uniquely shaped and color-coded icon to help +you identify the severity of a particular alert. These severity icons help you +immediately identify which alerts you should prioritize investigating: + + + +Alerts contain one of the following icons: + +- **Critical**: **{severity-critical}** and hexadecimal color `#8b2615` +- **High**: **{severity-high}** and hexadecimal color `#c0341d` +- **Medium**: **{severity-medium}** and hexadecimal color `#fca429` +- **Low**: **{severity-low}** and hexadecimal color `#fdbc60` +- **Info**: **{severity-info}** and hexadecimal color `#418cd8` +- **Unknown**: **{severity-unknown}** and hexadecimal color `#bababa` + +## Alert Management list + +NOTE: **Note:** +You will need at least Developer [permissions](../../permissions.md) to view the Alert Management list. + +You can find the Alert Management list at **{cloud-gear}** **Operations > Alerts** in your project's sidebar. +Each alert contains the following metrics: + + + +- **Severity** - The current importance of a alert and how much attention it should receive. +- **Start time** - How long ago the alert fired. This field uses the standard GitLab pattern of `X time ago`, but is supported by a granular date/time tooltip depending on the user's locale. +- **End time** - How long ago the alert fired was resolved. This field uses the standard GitLab pattern of `X time ago`, but is supported by a granular date/time tooltip depending on the user's locale. +- **Alert description** - The description of the alert, which attempts to capture the most meaningful data. +- **Event count** - The number of times that an alert has fired. +- **Status** - The [current status](#alert-management-statuses) of the alert. + +### Alert Management statuses + +Each alert contains a status dropdown to indicate which alerts need investigation. +Standard alert statuses include `triggered`, `acknowledged`, and `resolved`: + +- **Triggered**: No one has begun investigation. +- **Acknowledged**: Someone is actively investigating the problem. +- **Resolved**: No further work is required. + +## Alert Management details + +NOTE: **Note:** +You will need at least Developer [permissions](../../permissions.md) to view Alert Management details. + +Navigate to the Alert Management detail view by visiting the [Alert Management list](#alert-management-list) and selecting an Alert from the list. + + + +### Update an Alert's status + +The Alert Management detail view allows users to update the Alert Status. See [Alert Management statuses](#alert-management-statuses) for more details. diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index a95459e093a..23a50fd7766 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: Health +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Error Tracking > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/169) in GitLab 11.8. @@ -53,7 +59,7 @@ From error list, users can navigate to the error details page by clicking the ti This page has: - A link to the Sentry issue. -- A link to the GitLab commit if the Sentry [release id/version](https://docs.sentry.io/workflow/releases/?platform=javascript#configure-sdk) on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project. +- A link to the GitLab commit if the Sentry [release ID/version](https://docs.sentry.io/workflow/releases/?platform=javascript#configure-sdk) on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project. - Other details about the issue, including a full stack trace. - In [GitLab 12.7 and newer](https://gitlab.com/gitlab-org/gitlab/issues/36246), language and urgency are displayed. diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index f13fbcb2722..8716d5feb4a 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -1,3 +1,9 @@ +--- +stage: Release +group: Progressive Delivery +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Feature Flags **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. @@ -15,6 +21,13 @@ This helps reducing risk and allows you to easily manage which features to enabl GitLab offers a Feature Flags interface that allows you to create, toggle and remove feature flags. +<div class="video-fallback"> + <a href="https://www.youtube.com/watch?v=5tw2p6lwXxo">Watch</a> a use case between Feature Flags and Sentry Error Tracking +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/5tw2p6lwXxo" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + ## How it works Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature @@ -36,10 +49,10 @@ To add a new feature flag: 1. Click on the **New Feature Flag** button. 1. Give it a name. - NOTE: **Note:** - A name can contain only lowercase letters, digits, underscores (`_`) - and dashes (`-`), must start with a letter, and cannot end with a dash (`-`) - or an underscore (`_`). + NOTE: **Note:** + A name can contain only lowercase letters, digits, underscores (`_`) + and dashes (`-`), must start with a letter, and cannot end with a dash (`-`) + or an underscore (`_`). 1. Give it a description (optional, 255 characters max). 1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs) @@ -66,24 +79,59 @@ For example, you may not want to enable a feature flag on production until your first confirmed that the feature is working correctly on testing environments. To handle these situations, you can enable a feature flag on a particular environment -with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs). +with [Environment specs](../../../ci/environments/index.md#scoping-environments-with-specs). You can define multiple specs per flag so that you can control your feature flag more granularly. To define specs for each environment: 1. Navigate to your project's **Operations > Feature Flags**. 1. Click on the **New Feature Flag** button or edit an existing flag. -1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments. -1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs) and type the environment name. +1. Set the status of the default [spec](../../../ci/environments/index.md#scoping-environments-with-specs) (`*`). Choose a rollout strategy. This status and rollout strategy combination will be used for _all_ environments. +1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments/index.md#scoping-environments-with-specs) and type the environment name. 1. Set the status and rollout strategy of the additional spec. This status and rollout strategy combination takes precedence over the default spec since we always use the most specific match available. 1. Click **Create feature flag** or **Update feature flag**.  NOTE: **NOTE** -We'd highly recommend you to use the [Environment](../../../ci/environments.md) +We'd highly recommend you to use the [Environment](../../../ci/environments/index.md) feature in order to quickly assess which flag is enabled per environment. +## Feature flag behavior change in 13.0 + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0. + +Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environment specs, +without defining the strategy multiple times. + +This feature 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(:feature_flags_new_version) +``` + +To disable it: + +```ruby +Feature.disable(:feature_flags_new_version) +``` + +### Applying a strategy to environments + +After a strategy is defined, it applies to **All Environments** by default. To +make a strategy apply to a specific environment spec: + +1. Click the **Add Environment** button. +1. Create a new + [spec](../../../ci/environments/index.md#scoping-environments-with-specs). + +To apply the strategy to multiple environment specs, repeat these steps. + ## Feature Flag strategies GitLab Feature Flag adopts [Unleash](https://unleash.github.io) @@ -148,12 +196,12 @@ To get the access credentials that your application will need to talk to GitLab: 1. Navigate to your project's **Operations > Feature Flags**. 1. Click on the **Configure** button to see the values: - - **API URL**: URL where the client (application) connects to get a list of feature flags. - - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. - - **Application name**: The name of the running environment. For instance, - if the application runs for production server, application name would be - `production` or similar. This value is used for - [the environment spec evaluation](#define-environment-specs). + - **API URL**: URL where the client (application) connects to get a list of feature flags. + - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. + - **Application name**: The name of the running environment. For instance, + if the application runs for a production server, application name would be + `production` or similar. This value is used for + [the environment spec evaluation](#define-environment-specs). NOTE: **Note:** The meaning of these fields might change over time. For example, we are not sure @@ -231,7 +279,7 @@ func main() { Here's an example of how to integrate the feature flags in a Ruby application. -The Unleash client is given a user id for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. +The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. ```ruby #!/usr/bin/env ruby @@ -265,3 +313,4 @@ to control them in an automated flow: - [Feature Flags API](../../../api/feature_flags.md) - [Feature Flag Specs API](../../../api/feature_flag_specs.md) +- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md) diff --git a/doc/user/project/operations/img/alert_detail_v13_0.png b/doc/user/project/operations/img/alert_detail_v13_0.png Binary files differnew file mode 100644 index 00000000000..7da09407cd5 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_v13_0.png diff --git a/doc/user/project/operations/img/alert_management_1_v13_0.png b/doc/user/project/operations/img/alert_management_1_v13_0.png Binary files differnew file mode 100644 index 00000000000..dbc1e795b16 --- /dev/null +++ b/doc/user/project/operations/img/alert_management_1_v13_0.png diff --git a/doc/user/project/operations/img/alert_management_1_v13_1.png b/doc/user/project/operations/img/alert_management_1_v13_1.png Binary files differnew file mode 100644 index 00000000000..c01b4749eda --- /dev/null +++ b/doc/user/project/operations/img/alert_management_1_v13_1.png diff --git a/doc/user/project/operations/img/alert_management_severity_v13_0.png b/doc/user/project/operations/img/alert_management_severity_v13_0.png Binary files differnew file mode 100644 index 00000000000..f996d6e88f4 --- /dev/null +++ b/doc/user/project/operations/img/alert_management_severity_v13_0.png diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index df7ce61525e..954f88fe4f2 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -4,7 +4,7 @@ GitLab provides a variety of tools to help operate and maintain your applications: - Collect [Prometheus metrics](../integrations/prometheus_library/index.md). -- Deploy to different [environments](../../../ci/environments.md). +- Deploy to different [environments](../../../ci/environments/index.md). - Connect your project to a [Kubernetes cluster](../clusters/index.md). - Manage your infrastructure with [Infrastructure as Code](../../infrastructure/index.md) approaches. - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md index 620d9d70e4d..8e1117de4c7 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -13,7 +13,7 @@ You can add a button to the Monitoring dashboard linking directly to your existi  1. There should now be a button on your - [Monitoring dashboard](../../../ci/environments.md#monitoring-environments) which + [Monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) which will open the URL you entered in the above step.  diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md index 8282a980ced..07f60c37f1b 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -1,3 +1,9 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Tracing **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7903) in GitLab Ultimate 11.5. 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 172f5d4377f..6e48afad96a 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 @@ -1,5 +1,8 @@ --- type: concepts +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # DNS records overview 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 07bd2a61eb8..a5fc5b00b53 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 @@ -2,6 +2,9 @@ last_updated: 2019-07-04 type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Custom domains and SSL/TLS Certificates @@ -60,6 +63,11 @@ 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. + ##### For root domains Root domains (`example.com`) require: 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 f80b741fb77..8b180d438ef 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 @@ -1,6 +1,9 @@ --- type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab Pages integration with Let's Encrypt diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index bc51a9c90d2..e307b807aaa 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,5 +1,8 @@ --- type: concepts +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # SSL/TLS Certificates diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index ef30606a9ab..00cea846f91 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # New Pages website from a forked sample 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 027a238bf02..9a00b724753 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 @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Start a new Pages website from scratch or deploy an existing website diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md index 9c097c9acdb..745c50e8d65 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # New Pages website from a bundled template diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 645cc1c5795..4e95b5d5a69 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -1,6 +1,9 @@ --- last_updated: 2020-01-06 type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Creating and Tweaking GitLab CI/CD for GitLab Pages @@ -37,8 +40,8 @@ anything for them to work. Explaining [every detail of GitLab CI/CD](../../../ci/yaml/README.md) and GitLab Runner is out of the scope of this guide, but we'll need to understand just a few things to be able to write our own -`.gitlab-ci.yml` or tweak an existing one. It's an -[Yaml](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) file, +`.gitlab-ci.yml` or tweak an existing one. It's a +[YAML](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) file, with its own syntax. You can always check your CI syntax with the [GitLab CI/CD Lint Tool](https://gitlab.com/ci/lint). @@ -60,7 +63,7 @@ jekyll build ### Script -To transpose this script to Yaml, it would be like this: +To transpose this script to YAML, it would be like this: ```yaml script: @@ -364,7 +367,7 @@ from Jekyll `_config.yml` file, otherwise Jekyll will understand it as a regular directory to build together with the site: -```yml +```yaml exclude: - vendor ``` diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index b876e547ba5..c0bdd4b7f0b 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,6 +1,9 @@ --- last_updated: 2018-06-04 type: concepts, reference +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab Pages domain names, URLs, and baseurls diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 02bb8e13f4a..e81c9699153 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -2,6 +2,9 @@ description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' last_updated: 2019-06-04 type: index, reference +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab Pages diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index f77c572664a..e36dfd89ab3 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,6 +1,9 @@ --- type: reference last_updated: 2020-01-06 +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Exploring GitLab Pages @@ -86,11 +89,9 @@ When using Pages under the general domain of a GitLab instance (`*.example.io`), you _cannot_ use HTTPS with sub-subdomains. That means that if your username/groupname contains a dot, for example `foo.bar`, the domain `https://foo.bar.example.io` will _not_ work. This is a limitation of the -[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you +[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages will continue to work provided you don't redirect HTTP to HTTPS. -[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC" - GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). You can only create the highest-level group website. @@ -169,13 +170,10 @@ pages: - pages ``` -See an example that has different files in the [`master` branch][jekyll-master] -and the source files for Jekyll are in a [`pages` branch][jekyll-pages] which +See an example that has different files in the [`master` branch](https://gitlab.com/pages/jekyll-branched/tree/master) +and the source files for Jekyll are in a [`pages` branch](https://gitlab.com/pages/jekyll-branched/tree/pages) which also includes `.gitlab-ci.yml`. -[jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master -[jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages - ### Serving compressed assets Most modern browsers support downloading files in a compressed format. This diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 1d8119cfe87..7fe4c4c051d 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # GitLab Pages Access Control @@ -11,6 +14,9 @@ You can enable Pages access control on your project, so that only [members of your project](../../permissions.md#project-members-permissions) (at least Guest) can access your website: +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +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. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 6f68a2c9907..b134d283ba9 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -4,7 +4,7 @@ type: reference, howto # Protected Tags -> [Introduced][ce-10356] in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. Protected Tags allow control over who has permission to create tags as well as preventing accidental update or deletion once created. Each rule allows you to match either an individual tag name, or use wildcards to control multiple tags at once. @@ -67,5 +67,3 @@ 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. --> - -[ce-10356]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356 "Protected Tags" diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index e8d94a05e7e..eab88d59867 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -33,10 +33,10 @@ git push -o <push_option> You can use push options to skip a CI/CD pipeline, or pass environment variables. -| Push option | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------- | -| `ci.skip` | Do not create a CI pipeline for the latest push. | -| `ci.variable="<name>=<value>"` | Provide [environment variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | +| Push option | Description | Introduced in version | +| ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | +| `ci.skip` | Do not create a CI pipeline for the latest push. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | +| `ci.variable="<name>=<value>"` | Provide [environment variables](../../ci/variables/README.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 7937b7193d2..e2d0b616e4b 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -42,7 +42,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/remove_milestone` | ✓ | ✓ | | Remove milestone | | `/label ~label1 ~label2` | ✓ | ✓ | ✓ | Add label(s). Label names can also start without `~` but mixed syntax is not supported | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace existing label(s) with those specified | -| `/unlabel ~label1 ~label2` | ✓ | ✓ | ✓ | Remove all or specific label(s) | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove all or specific label(s) | | `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project | | `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project | | `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m` | diff --git a/doc/user/project/releases/img/edit_release_page_v13_0.png b/doc/user/project/releases/img/edit_release_page_v13_0.png Binary files differnew file mode 100644 index 00000000000..1b4343019af --- /dev/null +++ b/doc/user/project/releases/img/edit_release_page_v13_0.png diff --git a/doc/user/project/releases/img/release_milestone_dropdown_v13_0.png b/doc/user/project/releases/img/release_milestone_dropdown_v13_0.png Binary files differnew file mode 100644 index 00000000000..453c7ca93cc --- /dev/null +++ b/doc/user/project/releases/img/release_milestone_dropdown_v13_0.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index ca28a79abf4..bdb99d16625 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Releases @@ -102,12 +105,15 @@ The physical location of the asset can change at any time and the direct link wi ### Releases associated with milestones -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5. +> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/39467) to edit milestones in the UI in GitLab 13.0. Releases can optionally be associated with one or more [project milestones](../milestones/index.md#project-milestones-and-group-milestones) by including a `milestones` array in your requests to the -[Releases API](../../../api/releases/index.md#create-a-release). +[Releases API](../../../api/releases/index.md#create-a-release) or by using the dropdown in the [Edit Release](#editing-a-release) page. + + Releases display this association with the **Milestone** indicator in the top section of the Release block on the **Project overview > Releases** page, along @@ -190,22 +196,13 @@ the edit button (pencil icon) in the top-right corner of the release you want to This will bring you to the **Edit Release** page, from which you can change some of the release's details. - + -Currently, it is only possible to edit the release title, notes, and asset -links. To change other release information, such as its tag, associated -milestones, or release date, use the [Releases +Currently, it is only possible to edit the release title, notes, associated milestones, and asset +links. To change other release information, such as its tag, or release date, use the [Releases API](../../../api/releases/index.md#update-a-release). Editing this information through the **Edit Release** page is planned for a future version of GitLab. -Please note that the ability to edit asset links is currently behind a feature -flag which is disabled by default. For self-managed instances, it can be enabled -through the Rails console by a GitLab administrator with the following command: - -```ruby -Feature.enable(:release_asset_link_editing) -``` - ## Notification for Releases > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26001) in GitLab 12.4. @@ -258,6 +255,9 @@ generate Release Evidence for an existing release. Because of this, [each releas can have multiple Release Evidence snapshots. You can view the Release Evidence and its details on the Release page. +NOTE: **Note:** +When the issue tracker is disabled, release evidence [is not collected](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). + Release Evidence is stored as a JSON object, so you can compare evidence by using commonly-available tools. @@ -360,6 +360,39 @@ terminal. Read the [GitLab Releaser documentation](https://gitlab.com/gitlab-org/gitlab-releaser/-/tree/master/docs/index.md) for details. +## Set a deploy freeze + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. + +With a deploy freeze, you can prevent an unintended production release during a +period of time you specify, whether a company event or public holiday. You can +now rely on the enforcement of policies that are typically outside the scope of +GitLab to reduce uncertainty and risk when automating deployments. + +Deploy freeze periods are set at the Project level, and may be created and +managed using the [Freeze Periods API](../../../api/freeze_periods.md). +Each Freeze Period has a `freeze_start` and a `freeze_end`, which are defined +as [crontab](https://crontab.guru/) entries. If a project contains multiple +freeze periods, all will apply, and should they overlap, the freeze covers the +complete overlapped period. + +During pipeline processing, GitLab CI creates an environment variable named +`$CI_DEPLOY_FREEZE` if the currently executing job is within a +Freeze Period. + +To take advantage of this variable, create a `rules` entry in your +`gitlab-ci.yaml` to prevent the deployment job from executing. + +For example: + +```yaml +deploy_to_production: + stage: deploy + script: deploy_to_prod.sh + rules: + - if: $CI_DEPLOY_FREEZE == null +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 91e6d2912d1..ac10071e578 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -4,7 +4,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' # File finder -> [Introduced][gh-9889] in GitLab 8.4. +> [Introduced](https://github.com/gitlabhq/gitlabhq/pull/9889) in GitLab 8.4. The file finder feature allows you to search for a file in a repository using the GitLab UI. @@ -12,7 +12,7 @@ GitLab UI. You can find the **Find File** button when in the **Files** section of a project. - + For those who prefer to keep their fingers on the keyboard, there is a [shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ @@ -23,23 +23,20 @@ Press `t` to launch the File search function when in **Issues**, Start typing what you are searching for and watch the magic happen. With the up/down arrows, you go up and down the results, with `Esc` you close the search -and go back to **Files**. +and go back to **Files** ## How it works The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. -It implements a fuzzy search with highlight, and tries to provide intuitive +It implements a fuzzy search with the highlight and tries to provide intuitive results by recognizing patterns that people use while searching. -For example, consider the [GitLab CE repository][ce] and that we want to open +For example, consider the [GitLab FOSS repository](https://gitlab.com/gitlab-org/gitlab-foss/tree/master) and that we want to open the `app/controllers/admin/deploy_keys_controller.rb` file. -Using fuzzy search, we start by typing letters that get us closer to the file. +Using a fuzzy search, we start by typing letters that get us closer to the file. **Tip:** To narrow down your search, include `/` in your search terms. - - -[gh-9889]: https://github.com/gitlabhq/gitlabhq/pull/9889 "File finder pull request" -[ce]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master "GitLab CE repository" + diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 126144de703..a49701017f3 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -72,5 +72,3 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#removing-a-fork-relationship). - -[gitlab flow]: https://about.gitlab.com/blog/2014/09/29/gitlab-flow/ "GitLab Flow blog post" diff --git a/doc/user/project/repository/img/file_finder_find_button.png b/doc/user/project/repository/img/file_finder_find_button.png Binary files differdeleted file mode 100644 index 0c2d7d7bc73..00000000000 --- a/doc/user/project/repository/img/file_finder_find_button.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_finder_find_button_v12_10.png b/doc/user/project/repository/img/file_finder_find_button_v12_10.png Binary files differnew file mode 100644 index 00000000000..e93db946005 --- /dev/null +++ b/doc/user/project/repository/img/file_finder_find_button_v12_10.png diff --git a/doc/user/project/repository/img/file_finder_find_file.png b/doc/user/project/repository/img/file_finder_find_file.png Binary files differdeleted file mode 100644 index c2212c7cd9e..00000000000 --- a/doc/user/project/repository/img/file_finder_find_file.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_finder_find_file_v12_10.png b/doc/user/project/repository/img/file_finder_find_file_v12_10.png Binary files differnew file mode 100644 index 00000000000..1404ccc6d0b --- /dev/null +++ b/doc/user/project/repository/img/file_finder_find_file_v12_10.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index f9c953db3e3..055443daa1f 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -162,7 +162,7 @@ Via command line, you can commit multiple times before pushing. you will trigger a pipeline per push, not per commit. - **Skip pipelines:** You can add to you commit message the keyword - [`[ci skip]`](../../../ci/yaml/README.md#skipping-jobs) + [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline) and GitLab CI/CD will skip that pipeline. - **Cross-link issues and merge requests:** [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages) @@ -199,7 +199,7 @@ of commits to the fewest, and displayed on a nice graph: ## Repository graph -The repository graph displays visually the Git flow strategy used in that repository: +The repository graph displays the history of the repository network visually, including branches and merges. This can help you visualize the Git flow strategy used in the repository:  @@ -215,7 +215,7 @@ minutes.  Not all files are detected, among others; documentation, -vendored code, and most markup languages are excluded. This behaviour can be +vendored code, and most markup languages are excluded. This behavior can be adjusted by overriding the default. For example, to enable `.proto` files to be detected, add the following to `.gitattributes` in the root of your repository. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 8064eacf404..fdbea385998 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -55,6 +55,7 @@ For an existing project, you can set up push mirroring as follows: 1. Select **Push** from the **Mirror direction** dropdown. 1. Select an authentication method from the **Authentication method** dropdown, if necessary. 1. Check the **Only mirror protected branches** box, if necessary. +1. Check the **Keep divergent refs** box, if desired. 1. Click the **Mirror repository** button to save the configuration.  @@ -88,6 +89,27 @@ You can choose to only push your protected branches from GitLab to your remote r To use this option, check the **Only mirror protected branches** box when creating a repository mirror. +### Keep divergent refs **(CORE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. + +By default, if any ref on the remote mirror has diverged from the local +repository, the *entire push* will fail, and nothing will be updated. + +For example, if a repository has `master`, `develop`, and `stable` branches that +have been mirrored to a remote, and then a new commit is added to `develop` on +the mirror, the next push attempt will fail, leaving `master` and `stable` +out-of-date despite not having diverged. No change on any branch can be mirrored +until the divergence is resolved. + +With the **Keep divergent refs** option enabled, the `develop` branch is +skipped, allowing `master` and `stable` to be updated. The mirror status will +reflect that `develop` has diverged and was skipped, and be marked as a failed +update. + +NOTE: **Note:** +After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). + ## Setting up a push mirror from GitLab to GitHub **(CORE)** To set up a mirror from GitLab to GitHub, you need to follow these steps: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 19238839a5e..20143af0b33 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -2,21 +2,21 @@ type: concepts, howto --- -# Signing commits with x509 +# Signing commits and tags with X.509 -[x509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key +[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). -Personal x509 certificates are used for authentication or signing purposes +Personal X.509 certificates are used for authentication or signing purposes such as SMIME, but Git also supports signing of commits and tags -with x509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). -The main difference is the trust anchor which is the PKI for x509 certificates +with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). +The main difference is the trust anchor which is the PKI for X.509 certificates instead of a web of trust with GPG. -## How GitLab handles x509 +## How GitLab handles X.509 GitLab uses its own certificate store and therefore defines the trust chain. -For a commit to be *verified* by GitLab: +For a commit or tag to be *verified* by GitLab: - The signing certificate email must match a verified email address used by the committer in GitLab. - The Certificate Authority has to be trusted by the GitLab instance, see also @@ -25,9 +25,14 @@ For a commit to be *verified* by GitLab: which is usually up to three years. - The signing time is equal or later then commit time. -NOTE: **Note:** There is no certificate revocation list check in place at the moment. +NOTE: **Note:** Certificate revocation lists are checked on a daily basis via background worker. -## Obtaining an x509 key pair +NOTE: **Note:** Self signed certificates without `authorityKeyIdentifier`, +`subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We +recommend using certificates from a PKI that are in line with +[RFC 5280](https://tools.ietf.org/html/rfc5280). + +## Obtaining an X.509 key pair If your organization has Public Key Infrastructure (PKI), that PKI will provide an S/MIME key. @@ -37,12 +42,12 @@ own self-signed one, or purchase one. MozillaZine keeps a nice collection of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate) and some of them generate keys for free. -## Associating your x509 certificate with Git +## Associating your X.509 certificate with Git -To take advantage of X509 signing, you will need Git 2.19.0 or later. You can +To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can check your Git version with: -```sh +```shell git --version ``` @@ -52,7 +57,7 @@ If you have the correct version, you can proceed to configure Git. Configure Git to use your key for signing: -```sh +```shell signingkey = $( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' ) git config --global user.signingkey $signingkey git config --global gpg.format x509 @@ -64,21 +69,21 @@ Install [smimesign](https://github.com/github/smimesign) by downloading the installer or via `brew install smimesign` on MacOS. Get the ID of your certificate with `smimesign --list-keys` and set your -signingkey `git config --global user.signingkey ID`, then configure x509: +signingkey `git config --global user.signingkey ID`, then configure X.509: -```sh +```shell git config --global gpg.x509.program smimesign git config --global gpg.format x509 ``` ## Signing commits -After you have [associated your x509 certificate with Git](#associating-your-x509-certificate-with-git) you +After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you can start signing your commits: 1. Commit like you used to, the only difference is the addition of the `-S` flag: - ```sh + ```shell git commit -S -m "feat: x509 signed commits" ``` @@ -87,7 +92,7 @@ can start signing your commits: If you don't want to type the `-S` flag every time you commit, you can tell Git to sign your commits automatically: -```sh +```shell git config --global commit.gpgsign true ``` @@ -95,6 +100,34 @@ git config --global commit.gpgsign true To verify that a commit is signed, you can use the `--show-signature` flag: -```sh +```shell git log --show-signature ``` + +## Signing tags + +After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you +can start signing your tags: + +1. Tag like you used to, the only difference is the addition of the `-s` flag: + + ```shell + git tag -s v1.1.1 -m "My signed tag" + ``` + +1. Push to GitLab and check that your tags [are verified](#verifying-tags). + +If you don't want to type the `-s` flag every time you tag, you can tell Git +to sign your tags automatically: + +```shell +git config --global tag.gpgsign true +``` + +## Verifying tags + +To verify that a tag is signed, you can use the `--verify` flag: + +```shell +git tag --verify v1.1.1 +``` diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 8f4ec7bbbed..50343e52a68 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -10,6 +10,9 @@ Requirements allow you to create criteria to check your products against. They can be based on users, stakeholders, system, software, or anything else you find important to capture. +<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 diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index f18a202c63b..d021f259015 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,4 +1,4 @@ -# Service Desk **(PREMIUM)** +# Service Desk **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/149) in [GitLab Premium 9.1](https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#service-desk-eep). @@ -95,18 +95,18 @@ directory in your repository. Commit and push to your default branch. The **Thank you email** is the email sent to a user after they submit an issue. The file name of the template has to be `thank_you.md`. -You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue iid in the email and -`%{ISSUE_PATH}` placeholder which will be replaced by project path and the issue iid. +You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID in the email and +`%{ISSUE_PATH}` placeholder which will be replaced by project path and the issue IID. As the service desk issues are created as confidential (only project members can see them) -the response email doesn't provide the issue link. +the response email does not provide the issue link. #### New note email The **New note email** is the email sent to a user when the issue they submitted has a new comment. The file name of the template has to be `new_note.md`. -You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue iid +You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue IID in the email, `%{ISSUE_PATH}` placeholder which will be replaced by - project path and the issue iid and `%{NOTE_TEXT}` placeholder which will be replaced by the note text. + project path and the issue IID and `%{NOTE_TEXT}` placeholder which will be replaced by the note text. ### Using custom email display name @@ -115,11 +115,67 @@ 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 + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. + +NOTE: **Note:** +This feature is disabled by default. For steps to enable it, see [Enable custom email address](#enable-custom-email-address). + +If the `service_desk_email` feature flag is enabled in your configuration, +then it's possible to create Service Desk issues by sending emails to the +custom Service Desk email address, which should have the following format: +`project_contact+%{key}@example.com`. + +The `%{key}` part is used to find the project where the issue should be created. The +`%{key}` part combines the path to the project and configurable project name suffix: +`<project_full_path>-<project_name_suffix>`. + +You can set the project name suffix in your project's Service Desk settings. +It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). + + + +For example, suppose you add the following to your configuration: + +```yaml +service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_support@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true +``` + +In this case, suppose the `mygroup/myproject` project Service Desk settings has the project name +suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. +As a result, a new Service Desk issue is created from this email in the `mygroup/myproject` project. + +#### Enable custom email address + +This feature comes with the `service_desk_email` feature flag disabled by default. +To turn on the feature, ask a GitLab administrator with Rails console access to run the following +command: + +```ruby +Feature.enable(service_desk_email) +``` + +The configuration options are the same as for configuring +[incoming email](../../administration/incoming_email.md#set-it-up). + ## Using Service Desk ### As an end user (issue creator) -To create a Service Desk issue, an end user doesn't need to know anything about +To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and receive an email back confirming receipt: @@ -136,7 +192,7 @@ And any responses they send will be displayed in the issue itself. ### As a responder to the issue -For responders to the issue, everything works as usual. They'll see a familiar looking +For responders to the issue, everything works as usual. They will see a familiar looking issue tracker, where they can see issues created via customer support requests and filter and interact with them just like other GitLab issues. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 7f241a74820..e9521a0567e 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -12,6 +12,7 @@ See also: - [Project import/export API](../../../api/project_import_export.md) - [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(CORE ONLY)** +- [Group import/export](../../group/settings/import_export.md) - [Group import/export API](../../../api/group_import_export.md) To set up a project import/export: @@ -24,6 +25,8 @@ To set up a project import/export: Note the following: +- Imports from a newer version of GitLab are not supported. + The Importing GitLab version must be greater than or equal to the Exporting GitLab version. - Imports will fail unless the import and export GitLab instances are compatible as described in the [Version history](#version-history). - Exports are stored in a temporary [shared directory](../../../development/shared_files.md) @@ -41,11 +44,24 @@ Note the following: ## Version history -The following table lists updates to Import/Export: +Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. +This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) +releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Current version | Can import bundles exported from | +|-----------------|----------------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + +### 12.x + +Prior to 13.0 this was a defined compatibility table: | Exporting GitLab version | Importing GitLab version | | -------------------------- | -------------------------- | -| 11.7 to current | 11.7 to current | +| 11.7 to 13.0 | 11.7 to 13.0 | | 11.1 to 11.6 | 11.1 to 11.6 | | 10.8 to 11.0 | 10.8 to 11.0 | | 10.4 to 10.7 | 10.4 to 10.7 | @@ -66,6 +82,13 @@ Projects can be exported and imported only between versions of GitLab with match For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) and the exports between them will be compatible. +## Between CE and EE + +You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. +This assumes [version history](#version-history) requirements are met. + +If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../README.md). + ## Exported contents The following items will be exported: diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index ce94a8f5521..0c98772237b 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -20,6 +20,16 @@ Adjust your project's name, description, avatar, [default branch](../repository/ The project description also partially supports [standard Markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +#### Compliance framework **(ULTIMATE)** + +You can select a framework label to identify that your project has certain compliance requirements or needs additional oversight. Available labels include: + +- GDPR - General Data Protection Regulation +- HIPAA - Health Insurance Portability and Accountability Act +- PCI-DSS - Payment Card Industry-Data Security Standard +- SOC 2 - Service Organization Control 2 +- SOX - Sarbanes-Oxley + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -46,18 +56,19 @@ Use the switches to enable or disable the following features: | **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your docker images | -| **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-lfs) | +| **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration-premium-only) functionality | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | | **Pages** | ✓ | Allows you to [publish static websites](../pages/) | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - **Issue Boards** - - [**Service Desk**](#service-desk-premium) **(PREMIUM)** + - [**Service Desk**](#service-desk-starter) **(STARTER)** NOTE: **Note:** When the **Issues** option is disabled, you can still access **Milestones** @@ -70,13 +81,15 @@ Some features depend on others: - If you disable **Repository** functionality, GitLab also disables the following features for your project: - - **Merge Requests** - **Pipelines** - **Container Registry** - **Git Large File Storage** - **Packages** +- Metrics dashboard access requires reading both project environments and deployments. + Users with access to the metrics dashboard can also access environments and deployments. + #### Disabling email notifications Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) @@ -96,7 +109,7 @@ Set up your project's merge request settings:  -### Service Desk **(PREMIUM)** +### Service Desk **(STARTER)** Enable [Service Desk](../service_desk.md) for your project to offer customer support. @@ -247,7 +260,7 @@ To do so: 1. Confirm the action by typing the project's path as instructed. NOTE: **Note:** -Only project maintainers have the [permissions](../../permissions.md#project-members-permissions) +Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. ## Operations settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md new file mode 100644 index 00000000000..303a6f6d3be --- /dev/null +++ b/doc/user/project/settings/project_access_tokens.md @@ -0,0 +1,55 @@ +# Project access tokens **(CORE ONLY)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. + +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 expire on the date you define, at midnight UTC. + +For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/README.md#personalproject-access-tokens). + +## Creating a project access token + +1. Log in to GitLab. +1. Navigate to the project you would like to create an access token for. +1. In the **{settings}** **Settings** menu choose **Access Tokens**. +1. Choose a name and optional expiry date for the token. +1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token). +1. Click the **Create project access token** button. +1. Save the project access token somewhere safe. Once you leave or refresh + the page, you won't be able to access it again. + +## Project bot users + +For each project access token created, a bot user will also be created and added to the project with +["Maintainer" level permissions](../../permissions.md#project-members-permissions). API calls made with a +project access token will be associated to the corresponding bot user. + +These users will appear in **{settings}** **Settings > Members** but can not be modified. +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). + +## Revoking a project access token + +At any time, you can revoke any project access token by clicking the +respective **Revoke** button in **{settings}** **Settings > Access Tokens**. + +## Limiting scopes of a project access token + +Project access tokens can be created with one or more scopes that allow various +actions that a given token can perform. The available scopes are depicted in +the following table. + +| Scope | Description | +| ------------------ | ----------- | +| `api` | Grants complete read/write access to the scoped project API. | +| `read_api` | Grants read access to the scoped project API. | +| `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read-only access (pull) to the repository. | +| `write_repository` | Allows read-write access (pull, push) to the repository. | diff --git a/doc/user/project/static_site_editor/img/static_site_editor_v12_10.png b/doc/user/project/static_site_editor/img/static_site_editor_v12_10.png Binary files differdeleted file mode 100644 index 130dff9f30d..00000000000 --- a/doc/user/project/static_site_editor/img/static_site_editor_v12_10.png +++ /dev/null diff --git a/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_0.png b/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_0.png Binary files differnew file mode 100644 index 00000000000..a2f5248bf39 --- /dev/null +++ b/doc/user/project/static_site_editor/img/wysiwyg_editor_v13_0.png diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index f186ff9919e..e2e498b605a 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -5,7 +5,14 @@ description: "The static site editor enables users to edit content on static web # Static Site Editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. +> - [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. + +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 prior knowledge of the underlying templating language, site architecture, or @@ -44,7 +51,7 @@ When clicking it, GitLab will open up an editor window from which the content can be directly edited. When you're ready, you can submit your changes in a click of a button: - + When an editor submits their changes, in the background, GitLab automatically creates a new branch, commits their changes, and opens a merge request. The @@ -79,7 +86,8 @@ company and a new feature has been added to the company product. 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. +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. diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index d292ca94ba9..8ebfb638894 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -1,6 +1,12 @@ -# GitLab Status Page +--- +stage: Monitor +group: Health +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2479) in GitLab 12.10. +# GitLab Status Page **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2479) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. GitLab Status Page allows you to create and deploy a static website to communicate efficiently to users during an incident. @@ -35,15 +41,15 @@ To use GitLab Status Page you first need to set up your account details for your ### Status Page project -To deploy the status page to AWS S3 you need to add the Status Page project & configure the necessary CI variables. +To deploy the Status Page to AWS S3 you need to add the Status Page project & configure the necessary CI variables. 1. Fork the [Status Page](https://gitlab.com/gitlab-org/status-page) project. This can also be done via [Repository Mirroring](https://gitlab.com/gitlab-org/status-page#repository-mirroring) which will ensure you get the up-to-date Status Page features. 1. Add the following variables in **Settings > CI/CD > Variables**. (To get these variables from Amazon, use your Amazon Console): - - `S3_BUCKET_NAME` - name of the Amazon S3 bucket + - `S3_BUCKET_NAME` - name of the Amazon S3 bucket (If a bucket with the provided name doesn't exist, the first pipeline run will create one and configure it for [static website hosting](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html)) - `AWS_DEFAULT_REGION` - the AWS region - `AWS_ACCESS_KEY_ID` - the AWS access key ID - `AWS_SECRET_ACCESS_KEY` - the AWS secret -1. Run the pipeline to deploy the status page to S3. +1. Run the pipeline to deploy the Status Page to S3. ### Syncing incidents to the Status Page @@ -55,7 +61,7 @@ Once the CI/CD variables are set, you'll need to set up the Project you want to ## Status Page UI -The Status page landing page shows you an overview of the recent incidents. Clicking on an incident will take you to the incident's detail page. +The Status Page landing page shows you an overview of the recent incidents. Clicking on an incident will take you to the incident's detail page.  @@ -64,8 +70,8 @@ The Status page landing page shows you an overview of the recent incidents. Clic The incident detail page shows detailed information about a particular incident. For example: - Status on the incident, including when the incident was last updated. -- The incident title. -- The description of the incident. +- The incident title, including any emojis. +- The description of the incident, including emojis and static images. - A chronological ordered list of updates to the incident.  @@ -76,7 +82,9 @@ The incident detail page shows detailed information about a particular incident. To publish an Incident, you first need to create an issue in the Project you enabled the Status Page settings in. -Once this issue is created, a background worker will publish the issue onto the status page using the credentials you provided during setup. +Once this issue is created, a background worker will publish the issue onto the Status Page using the credentials you provided during setup. +Since all incidents are published publicly, user and group mentions are anonymized with `Incident Responder`, +and titles of non-public [GitLab references](../../markdown.md#special-gitlab-references) are removed. NOTE: **Note:** Confidential issues are not published. If a published issue is made confidential it will be unpublished. @@ -99,4 +107,4 @@ Anyone with access to view the Issue can add an Emoji Award to a comment, so you ### Changing the Incident status -To change the incident status from `open` to `closed`, close the incident issue within GitLab. This will then be updated shortly on the Status page website. +To change the incident status from `open` to `closed`, close the incident issue within GitLab. This will then be updated shortly on the Status Page website. diff --git a/doc/user/project/web_ide/img/admin_clientside_evaluation.png b/doc/user/project/web_ide/img/admin_clientside_evaluation.png Binary files differdeleted file mode 100644 index a930490398b..00000000000 --- a/doc/user/project/web_ide/img/admin_clientside_evaluation.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/admin_live_preview_v13_0.png b/doc/user/project/web_ide/img/admin_live_preview_v13_0.png Binary files differnew file mode 100644 index 00000000000..90129d240bc --- /dev/null +++ b/doc/user/project/web_ide/img/admin_live_preview_v13_0.png diff --git a/doc/user/project/web_ide/img/dark_theme_v13.0.png b/doc/user/project/web_ide/img/dark_theme_v13.0.png Binary files differnew file mode 100644 index 00000000000..6034bc52c05 --- /dev/null +++ b/doc/user/project/web_ide/img/dark_theme_v13.0.png diff --git a/doc/user/project/web_ide/img/clientside_evaluation.png b/doc/user/project/web_ide/img/live_preview_v13_0.png Binary files differindex bd04d3d644b..bd04d3d644b 100644 --- a/doc/user/project/web_ide/img/clientside_evaluation.png +++ b/doc/user/project/web_ide/img/live_preview_v13_0.png diff --git a/doc/user/project/web_ide/img/solarized_light_theme_v13.0.png b/doc/user/project/web_ide/img/solarized_light_theme_v13.0.png Binary files differnew file mode 100644 index 00000000000..f3c4aa142a4 --- /dev/null +++ b/doc/user/project/web_ide/img/solarized_light_theme_v13.0.png diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index c98448ff904..d4daca0e1e4 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,6 +1,6 @@ # Web IDE -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate][ee] 10.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. > - [Brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/issues/44157) in 10.7. The Web IDE editor makes it faster and easier to contribute changes to your @@ -15,7 +15,7 @@ and from merge requests. ## File finder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core][ce] 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. The file finder allows you to quickly open files in the current branch by searching. The file finder is launched using the keyboard shortcut `Command-p`, @@ -43,6 +43,20 @@ you can find a more complete list of supported languages in the NOTE: **Note:** Single file editing is based on the [Ace Editor](https://ace.c9.io). +### Themes + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab 13.0. + +All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor. +You can pick a theme from your [profile preferences](../../profile/preferences.md). + +The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808), +which applies to the entire Web IDE screen. + +| Solarized Light Theme | Dark Theme | +|---------------------------------------------------------------|-----------------------------------------| +|  |  | + ## Commit changes > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4 and [brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/issues/44157) in 10.7. @@ -73,7 +87,7 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Core][ce] 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed @@ -86,7 +100,7 @@ left. ## Switching merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Core][ce] 11.0. +> [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 @@ -95,34 +109,35 @@ request. ## Switching branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Core][ce] 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. 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 different branch. -## Client Side Evaluation +## Live Preview -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core][ce] 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. This feature uses CodeSandbox to compile and bundle the JavaScript used to preview the web application. - + Additionally, for public projects an **Open in CodeSandbox** button is available to transfer the contents of the project into a public CodeSandbox project to quickly share your project with others. -### Enabling Client Side Evaluation +### Enabling Live Preview -The Client Side Evaluation feature needs to be enabled in the GitLab instances -admin settings. Client Side Evaluation is enabled for all projects on +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 @@ -302,6 +317,3 @@ active terminal at a time. - If the terminal displays **Connection Failure**, then the terminal could not connect to the runner. Please try to stop and restart the terminal. If the problem persists, double check your runner configuration. - -[ce]: https://about.gitlab.com/pricing/ -[ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 88b729272ec..fa3ad4536ef 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -126,7 +126,7 @@ found. The list is ordered alphabetically.  If you have many pages, not all will be listed in the sidebar. Click on -**More pages** to see all of them. +**View All Pages** to see all of them. ## Viewing the history of a wiki page @@ -189,7 +189,24 @@ instructions. On the project's Wiki page, there is a right side navigation that renders the full Wiki pages list by default, with hierarchy. -If the Wiki repository contains a `_sidebar` page, the file of this page replaces the default side navigation. -This custom file serves to render it's custom content, fully replacing the standard sidebar. +To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. + +CAUTION: **Warning:** +Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly +from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). + +Example for `_sidebar` (using Markdown format): + +```markdown +### [Home](home) + +- [Hello World](hello) +- [Foo](foo) +- [Bar](bar) + +--- + +- [Sidebar](_sidebar) +``` Support for displaying a generated TOC with a custom side navigation is planned. |
